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_short_name": "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 to organization administrators when the set of invitations changes; this tells clients they need to refetch data from `GET /invites` if they are displaying UI containing active invitations. 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. Processing this event is important to being able to display basic details on other users given only their ID. 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", "user_id": 38, "avatar_version": 1, "is_admin": false, "is_owner": false, "is_guest": 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 all users in a Zulip organization when a user is 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 long offline. While most presence updates happen done via polling the main presence endpoint, this event is important to avoid confusing users when someone comes online and then immediately sends a message (one wouldn't want them to still appear offline at that point!). properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - presence user_id: type: integer description: | The ID of modified user. email: type: string description: | The 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: | An object contatining a set of objects which describe the the user's presence on various platforms. additionalProperties: $ref: "#/components/schemas/Presence" additionalProperties: false example: { "type": "presence", "user_id": 10, "email": "user10@zulip.testserver", "server_timestamp": 1594825445.320078373, "presence": { "ZulipAndroid/1.0": { "client": "ZulipAndroid/1.0", "status": "idle", "timestamp": 1594825445, "pushable": false, }, }, "id": 0, } - type: object description: | Event sent when a new stream is created to users who can see the new stream exists (for private streams, only subscribers and organization administrators will receive this event). Note that organization administrators who are not subscribed will not be able to see content on the stream; just that it exists. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - create streams: type: array description: | Array of stream objects, each containing details about the newly added stream(s). items: $ref: "#/components/schemas/BasicStream" additionalProperties: false example: { "type": "stream", "op": "create", "streams": [ { "name": "private", "stream_id": 12, "description": "", "rendered_description": "", "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, }, ], "id": 0, } - type: object description: | Event sent to all users who can see a stream when it is deactivated. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - delete streams: type: array description: | Array of stream objects, each contatining details about a stream that was deleted. items: $ref: "#/components/schemas/BasicStream" additionalProperties: false example: { "type": "stream", "op": "delete", "streams": [ { "name": "private", "stream_id": 12, "description": "", "rendered_description": "", "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, }, ], "id": 0, } - type: object description: | Event sent to all users who can see that a stream exists when a property of that stream changes. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - stream op: type: string enum: - update stream_id: type: integer description: | The ID of the stream whose details have changed. name: type: string description: | The name of the stream whose details have changed. property: type: string description: | The property of the stream which has changed. See [/stream GET](/api/get-streams) for details on the various properties of a stream. Clients should handle an "unknown" property received here without crashing, since that can happen when connecting to a server running a newer version of Zulip with new features. value: description: | The new value of the changed property. oneOf: - type: integer - type: boolean - type: string rendered_description: type: string description: | Note: Only present if the changed property was `description`. The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. history_public_to_subscribers: type: boolean description: | Note: Only present if the changed property was `invite_only`. Whether the history of the stream is public to its subscribers. Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future. additionalProperties: false example: { "op": "update", "type": "stream", "property": "invite_only", "value": true, "history_public_to_subscribers": true, "stream_id": 11, "name": "test_stream", "id": 0, } - 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/EmojiReactionBase" - additionalProperties: false properties: emoji_code: {} emoji_name: {} reaction_type: {} user_id: {} user: {} 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. 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, } - 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/EmojiReactionBase" - additionalProperties: false properties: emoji_code: {} emoji_name: {} reaction_type: {} user_id: {} user: {} 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. 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 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 in a Zulip organization when the status of a user changes. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_status away: type: boolean description: | Whether the user has marked themself "away". status_text: type: string description: | The text content of the status message. 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", "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when new custom profile field types are configured for that Zulip organization. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - custom_profile_fields fields: type: array description: | An array of dictionaries where each dictionary contains details of a single new custom profile field for the Zulip organization. items: $ref: "#/components/schemas/CustomProfileField" example: { "type": "custom_profile_fields", "fields": [ { "id": 1, "name": "Phone number", "type": 1, "hint": "", "field_data": "", "order": 1, }, { "id": 2, "name": "Biography", "type": 2, "hint": "What are you known for?", "field_data": "", "order": 2, }, { "id": 3, "name": "Favorite food", "type": 1, "hint": "Or drink, if you'd prefer", "field_data": "", "order": 3, }, { "id": 4, "name": "Favorite editor", "type": 3, "hint": "", "field_data": '{"vim":{"text":"Vim","order":"1"},"emacs":{"text":"Emacs","order":"2"}}', "order": 4, }, { "id": 5, "name": "Birthday", "type": 4, "hint": "", "field_data": "", "order": 5, }, { "id": 6, "name": "Favorite website", "type": 5, "hint": "Or your personal blog's URL", "field_data": "", "order": 6, }, { "id": 7, "name": "Mentor", "type": 6, "hint": "", "field_data": "", "order": 7, }, { "id": 8, "name": "GitHub", "type": 7, "hint": "Enter your GitHub username", "field_data": '{"subtype":"github"}', "order": 8, }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when an organization administrator changes the organization's configured default stream groups. Default stream groups are an **experimental** feature that is not yet stabilized. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - default_stream_groups default_stream_groups: type: array description: | An array of dictionaries where each dictionary contains details about a single default stream group. items: $ref: "#/components/schemas/DefaultStreamGroup" example: { "type": "default_stream_groups", "default_stream_groups": [ { "name": "group1", "id": 2, "description": "New description", "streams": [ { "name": "Scotland", "stream_id": 3, "description": "Located in the United Kingdom", "rendered_description": "Located in the United Kingdom
", "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, }, { "name": "Denmark", "stream_id": 1, "description": "A Scandinavian country", "rendered_description": "A Scandinavian country
", "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, }, { "name": "Verona", "stream_id": 5, "description": "A city in Italy", "rendered_description": "A city in Italy
", "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, }, ], }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when the default streams in the organization are changed by an organization administrator. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - default_streams default_streams: type: array description: | An array of dictionaries where each dictionary contains details about a single default stream. items: $ref: "#/components/schemas/BasicStream" example: { "type": "default_streams", "default_streams": [ { "name": "Scotland", "stream_id": 3, "description": "Located in the United Kingdom", "rendered_description": "Located in the United Kingdom
", "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, }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a message has been deleted. Sent to all users who received the message. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - delete_message message_ids: type: array description: | The `message_ids` property will be present for clients that support the `bulk_message_deletion` client capability. An containing the IDs of the newly deleted messages. items: type: integer message_id: type: integer description: | The `message_id` property will be present for clients that do not support the `bulk_message_deletion` client capability. The ID of the newly deleted message. message_type: type: string description: | The type of message. Either 'stream' or 'private'. The other keys present in the event, necessary to update various frontend data structures that might be tracking the message, depend on the message type. enum: - private - stream recipient_id: type: integer description: | Only present for private messages. The ID of the user (or group of users) who received the private message. sender_id: type: integer description: | Only present for private messages. The ID of the user who sent the private message. stream_id: type: integer description: | Only present for stream messages. The ID of the stream to which the message was sent. topic: type: string description: | Only present for stream messages. The topic to which the message was sent. example: { "type": "delete_message", "recipient_id": 10, "sender_id": 8, "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 description: | Array of tuples, where each tuple describes a muted topic. The first element of tuple is the stream name in which the topic has to be muted, the second element is the topic name to be muted and the third element is an integer UNIX timestamp representing when the topic was muted. 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 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: | Event sent when the set of onboarding "hotspots" to show for the current user have changed (E.g. because the user dismissed one). Clients that feature a similar tutorial experience to the Zulip webapp may want to handle these events. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - hotspots hotspots: type: array description: | An array of dictionaries where each dictionary contains details about a single hotspot. items: $ref: "#/components/schemas/Hotspot" example: { "type": "hotspots", "hotspots": [ { "name": "intro_streams", "title": "Catch up on a stream", "description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.", "delay": 0.5, }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a message has been edited. Sent to all users who had received the original message. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - update_message user_id: type: integer description: | The ID of the user who sent the message. message_id: type: integer description: | The ID of the message which was edited. This field should be used to apply content edits to the client's cached message history. If the stream or topic was changed, the set of moved messages is encoded in the separate `message_ids` field, which is guaranteed to include `message_id`. message_ids: type: array items: type: integer description: | The list of IDs of messages to which any stream or topic changes encoded in this event should be applied. These messages are guaranteed to have all been previously sent to stream `stream_id` with topic `orig_subject`, and have been moved to `new_stream_id` with topic `subject` (if those fields are present in the event). Clients processing these events should update all cached message history associated with the moved messages (including adjusting `unread_msgs` data structures, where the client may not have the message itself in its history) to reflect the new stream and topic. Content changes should be applied only to the single message indicated by `message_id`. edit_timestamp: type: integer description: | The time when this message edit operation was processed by the server. stream_name: type: string description: | Only present if the message was originally sent to a stream. The name of the stream that the message was sent to. Clients are recommended to use the `stream_id` field instead. stream_id: type: integer description: | Only present if the message was originally sent to a stream. The pre-edit stream for all of the messages with IDs in `message_ids`. new_stream_id: type: integer description: | Note: Only present if message(s) were moved to a different stream. The post-edit stream for all of the messages with IDs in `message_ids`. propagate_mode: type: string description: | The choice the editing user made about which messages should be affected by a stream/topic edit: just the one indicated in `message_id`, messages in the same topic that had been sent after this one, or 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 webapp 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: | The pre-edit topic for all of the messages with IDs in `message_ids`. Only present if this event moved messages to a different topic. subject: type: string description: | The post-edit topic for all of the messages with IDs in `message_ids`. Only present if this event moved messages to a different topic. 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 filter](/help/add-a-custom-linkifier) that match content in the message's topic.), corresponding to the post-edit topic. Only present if this event moved messages to a different 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: | 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: | The original content of the message with ID `message_id` immediately prior to this edit, rendered as HTML. prev_rendered_content_version: type: integer description: | The Markdown processor version number for the pre-edit message. Clients should ignore this field. content: type: string description: | The new content of the message with ID `message_id`, in the original Markdown. rendered_content: type: string description: | The new content of the message with ID `message_id`, rendered in HTML. is_me_message: type: boolean description: | 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 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. [message-flags]: /api/update-message-flags#available-flags items: type: string 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
", "prev_rendered_content_version": 1, "is_me_message": false, "propagate_mode": "change_all", "stream_id": 5, "orig_subject": "test", "subject": "new_topic", "topic_links": [], "message_ids": [58, 57], "flags": [], "id": 0, } - type: object additionalProperties: false description: | Event sent when a user starts typing a message. Sent to all clients for users who would receive the message being typed, with the additional rule that typing notifications for stream messages are only sent to clients that included `stream_typing_notifications` in their `client_capabilities` when registering the event queue. **Changes**: Typing notifications for stream messages are new in Zulip 4.0 (feature level 58). See the [typing endpoint docs](/api/set-typing-status) for more details. 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 "private", as with sending a message. **Changes**: New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly private `private`. enum: - private - stream sender: additionalProperties: false type: object description: | Object describing the "sender" (i.e. the user who is typing a message). properties: user_id: type: integer description: | The user's ID. email: type: string description: | The Zulip display email address for the user. recipients: type: array description: | Only present if `message_type` is `private`. Array of dictionaries describing the set of users who would be recipients of the message being typed. Each dictionary contains details on one one of the recipients users; 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 display email address for the user. stream_id: type: integer description: | Only present if `message_type` is `stream`. The unique ID of the stream to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for private messages. topic: type: string description: | Only present if `message_type` is `stream`. Topic within the stream where the message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for private messages. example: { "type": "typing", "op": "start", "sender": { "user_id": 10, "email": "user10@zulip.testserver", }, "recipients": [ { "user_id": 8, "email": "user8@zulip.testserver", }, { "user_id": 10, "email": "user10@zulip.testserver", }, ], "id": 0, } - type: object additionalProperties: false description: | Event sent when a user stops typing a message. Sent to all clients for users who would receive the message that was previously being typed, with the additional rule that typing notifications for stream messages are only sent to clients that included `stream_typing_notifications` in their `client_capabilities` when registering the event queue. **Changes**: Typing notifications for stream messages are new in Zulip 4.0 (feature level 58). See the [typing endpoint docs](/api/set-typing-status) for more details. 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 "private", as with sending a message. **Changes**: New in Zulip 4.0 (feature level 58). Previously, all typing notifications were implicitly private `private`. enum: - private - stream sender: additionalProperties: false type: object description: | Object describing the "sender" (i.e. the user who was previously typing a message). properties: user_id: type: integer description: | The user's ID. email: type: string description: | The Zulip display email address for the user. recipients: type: array description: | Only present for typing notifications for (group) private messages. Array of dictionaries describing the set of users who would be recipients of the message that stopped being typed. Each dictionary contains details on one one of the recipients users; 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 display email address for the user. stream_id: type: integer description: | Only present if `message_type` is `stream`. The unique ID of the stream to which message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for private messages. topic: type: string description: | Only present if `message_type` is `stream`. Topic within the stream where the message is being typed. **Changes**: New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for private messages. example: { "type": "typing", "op": "stop", "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 a message. [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: - add operation: deprecated: true description: | Old name for `op` for this event type. **Deprecated**: This is deprecated; please use `op` instead starting with Zulip 4.0 (feature level 32). type: string enum: - add flag: type: string description: | The flag 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 flag was added to all messages (E.g. all messages were marked as read). If this is true, 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 a message. [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 `op` for this event type. **Deprecated**: This is deprecated; please use `op` instead starting with Zulip 4.0 (feature level 32). enum: - remove flag: type: string description: | The flag to be removed. messages: type: array description: | Array containing the IDs of the messages from which the flag was removed. items: type: integer all: type: boolean description: | Whether the flag was removed from all messages. If this is true then the `messages` array will be empty. example: { "type": "update_message_flags", "op": "remove", "operation": "remove", "flag": "starred", "messages": [63], "all": false, "id": 0, } - type: object additionalProperties: false description: | Event sent to users in an organization when a [user group](/help/user-groups) is created. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - add group: $ref: "#/components/schemas/UserGroup" example: { "type": "user_group", "op": "add", "group": { "name": "backend", "members": [12], "description": "Backend team", "id": 2, }, "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when a property of a user group is changed. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - update group_id: type: integer description: | The ID of the user group whose details have changed. data: type: object additionalProperties: false description: | Dictionary containing the changed details of the user group. properties: name: type: string description: | The new name of the user group. Only present if the group's name changed. description: type: string description: | The new description of the group. Only present if the description changed. example: { "type": "user_group", "op": "update", "group_id": 2, "data": { "description": "Mention this group to get the security team's attention.", }, "id": 0, } - type: object additionalProperties: false description: | Event sent to all users when users have been added to a user group. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - add_members group_id: type: integer description: | The ID of the user group with new members. user_ids: type: array items: type: integer description: | Array containing the IDs of the users who have been added to the user group. example: { "type": "user_group", "op": "add_members", "group_id": 2, "user_ids": [10], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users when users have been removed from a user group. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - remove_members group_id: type: integer description: | The ID of the user group whose details have changed. user_ids: type: array items: type: integer description: | Array containing the IDs of the users who have been removed from the user group. example: { "type": "user_group", "op": "remove_members", "group_id": 2, "user_ids": [10], "id": 0, } - type: object additionalProperties: false description: | Event sent to all users when a user group has been deleted. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - user_group op: type: string enum: - remove group_id: type: integer description: | The ID of the group which has been deleted. example: { "type": "user_group", "op": "remove", "group_id": 2, "id": 0, } - type: object additionalProperties: false description: | Event sent to all users in a Zulip organization when the set of configured [linkifiers](/help/add-a-custom-linkifier) for the organization has changed. Processing this event is important to doing Markdown local echo correctly. **Changes**: New in Zulip 4.0 (feature level 54), replacing the previous `realm_filters` event type, which is still sent for backwards compatibility reasons. Clients should migrate to requesting and processing the `realm_linkifiers` event type when possible, since we plan to remove the legacy `realm_filters` logic entirely in a future release. properties: id: $ref: "#/components/schemas/EventIdSchema" type: allOf: - $ref: "#/components/schemas/EventTypeSchema" - enum: - realm_linkifiers realm_linkifiers: type: array description: | Array of dictionaries where each dictionary contains details about a single realm linkifier. 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_format: type: string description: | The URL format string to be used for linkifying matches. id: type: integer description: | The ID of the linkifier. example: { "type": "realm_linkifiers", "realm_linkifiers": [ { "pattern": "#(?PSecurity 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 tags: ["messages"] description: | Send a stream or a private message. `POST {{ api_url }}/v1/messages` parameters: - name: type in: query description: | The type of message to be sent. `private` for a private message and `stream` for a stream message. schema: type: string enum: - private - stream example: private required: true - name: to in: query description: | For stream messages, either the name or integer ID of the stream. For private messages, either a list containing integer user IDs or a list containing string email addresses. **Changes**: Support for using user/stream IDs was added in Zulip 2.0.0. content: application/json: schema: type: array items: type: integer example: [9, 10] required: true - $ref: "#/components/parameters/RequiredContent" - $ref: "#/components/parameters/Topic" - name: queue_id in: query schema: type: string description: | For clients supporting [local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo), the [event queue](/api/register-queue) ID for the client. If passed, `local_id` is required. If the message is successfully sent, the server will include `local_id` in the `message` event that the client with this `queue_id` will receive notifying it of the new message via [`GET /events`](/api/get-events). This lets the client know unambiguously that it should replace the locally echoed message, rather than adding this new message (which would be correct if the user had sent the new message from another device). example: "1593114627:0" - name: local_id in: query schema: type: string description: | For clients supporting local echo, a unique string-format identifier chosen freely by the client; the server will pass it back to the client without inspecting it, as described in the `queue_id` description. example: "100.01" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} id: type: integer description: | The unique ID assigned to the sent message. deliver_at: type: string description: | Present for scheduled messages, encodes the time when the message will be sent. Note that scheduled messages ("Send later") is a beta API and may change before it's a finished feature. example: "2020-06-24 11:19:54.337533+00:00" example: {"msg": "", "id": 42, "result": "success"} "400": description: Bad request. content: application/json: schema: oneOf: - $ref: "#/components/schemas/NonExistingStreamError" - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "Invalid email 'eeshan@zulip.com'", "result": "error", } /messages/{message_id}/history: get: operationId: get_message_history tags: ["messages"] description: | Fetch the message edit history of a previously edited message. `GET {{ api_url }}/v1/messages/{message_id}/history` 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" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} message_history: type: array items: type: object additionalProperties: false properties: topic: type: string description: | the topic for the message. prev_topic: type: string description: | the topic for the message before being edited. content: type: string description: | the body of the message. rendered_content: type: string description: | the already rendered, HTML version of `content`. prev_content: type: string description: | the body of the message before being edited. prev_rendered_content: type: string description: | the already rendered, HTML version of `prev_content`. user_id: type: integer description: | the ID of the user that made the edit. content_html_diff: type: string description: | 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 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!
foo
", "result": "success", } /messages/{message_id}/reactions: post: operationId: add_reaction tags: ["messages"] description: | Add an [emoji reaction](/help/emoji-reactions) to a message. `POST {{ api_url }}/v1/messages/{message_id}/reactions` parameters: - $ref: "#/components/parameters/MessageId" - name: emoji_name in: query description: | The target emoji's human-readable name. To find an emoji's name, hover over a message to reveal three icons on the right, then click the smiley face icon. Images of available reaction emojis appear. Hover over the emoji you want, and note that emoji's text name. schema: type: string example: "octopus" required: true - $ref: "#/components/parameters/EmojiCode" - $ref: "#/components/parameters/ReactionType" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid emoji code", "code": "BAD_REQUEST", } delete: operationId: remove_reaction tags: ["messages"] description: | Remove an [emoji reaction](/help/emoji-reactions) from a message. `DELETE {{ api_url }}/v1/messages/{message_id}/reactions` parameters: - $ref: "#/components/parameters/MessageId" - name: emoji_name in: query description: | The target emoji's human-readable name. To find an emoji's name, hover over a message to reveal three icons on the right, then click the smiley face icon. Images of available reaction emojis appear. Hover over the emoji you want, and note that emoji's text name. schema: type: string example: "octopus" required: false - $ref: "#/components/parameters/EmojiCode" - $ref: "#/components/parameters/ReactionType" responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Invalid message(s)", "code": "BAD_REQUEST", } /messages/matches_narrow: get: operationId: check_messages_match_narrow tags: ["messages"] description: | Check whether a set of messages match a [narrow](/api/construct-narrow). `GET {{ api_url }}/v1/messages/matches_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 of `GET /messages`, so that a client can splice these fields into a `message` object received from `GET /events` and end up with an extended message object identical to how a `GET /messages` 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). 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: {} 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_raw_message tags: ["messages"] description: | Get the raw content of a message. `GET {{ api_url }}/v1/messages/{msg_id}` This is a rarely-used endpoint relevant for clients that primarily work with HTML-rendered messages but might need to occasionally fetch the message's raw Markdown (e.g. for pre-filling a message-editing UI). parameters: - $ref: "#/components/parameters/MessageId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} raw_content: type: string description: | The raw content of the message. example: { "raw_content": "**Don't** forget your towel!", "result": "success", "msg": "", } "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/InvalidMessageError" patch: operationId: update_message tags: ["messages"] description: | Edit/update the content or topic of a message. `PATCH {{ api_url }}/v1/messages/{msg_id}` `{msg_id}` in the above URL should be replaced with the ID of the message you wish you update. parameters: - $ref: "#/components/parameters/MessageId" - $ref: "#/components/parameters/Topic" - name: propagate_mode in: query description: | Which message(s) should be edited: just the one indicated in `message_id`, messages in the same topic that had been sent after this one, or all of them. This parameter determines both which messages get moved and also whether clients that are currently narrowed to the topic containing the message should navigate or adjust their compose box recipient to point to the post-edit stream/topic. schema: type: string enum: - change_one - change_later - change_all default: change_one example: change_all - name: send_notification_to_old_thread in: query description: | Whether to send breadcrumb message to the old thread to notify users where the messages were moved to. **Changes**: New in Zulip 3.0 (feature level 9). schema: type: boolean default: true example: true - name: send_notification_to_new_thread in: query description: | Whether to send a notification message to the new thread to notify users where the messages came from. **Changes**: New in Zulip 3.0 (feature level 9). schema: type: boolean default: true example: true - $ref: "#/components/parameters/OptionalContent" - name: stream_id in: query description: | The ID of the stream to access. schema: type: integer example: 42 responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" "400": description: Bad request. content: application/json: schema: 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", } delete: operationId: delete_message tags: ["messages"] description: | Permanently delete a message. `DELETE {{ api_url }}/v1/messages/{msg_id}` This API corresponds to the [delete a message completely][delete-completely] feature documented in the Zulip Help Center. parameters: - $ref: "#/components/parameters/MessageId" responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - $ref: "#/components/schemas/InvalidMessageError" - allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "You don't have permission to delete this message", "result": "error", } /user_uploads: post: operationId: upload_file tags: ["messages"] description: | Upload a single file and get the corresponding URI. `POST {{ api_url }}/v1/user_uploads` Initially, only you will be able to access the link. To share the uploaded file, you'll need to [send a message][send-message] containing the resulting link. Users who can already access the link can reshare it with other users by sending additional Zulip messages containing the link. [uploaded-files]: /help/manage-your-uploaded-files [send-message]: /api/send-message 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: {} uri: type: string description: | The URI of the uploaded file. example: { "msg": "", "result": "success", "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", } /user_uploads/{realm_id_str}/{filename}: get: operationId: get_file_temporary_url tags: ["messages"] description: | Get a temporary URL for access to the file that doesn't require authentication. 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: {} 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 tags: ["users"] description: | Retrieve details on all users in the organization. Optionally includes values of [custom profile field](/help/add-custom-profile-fields). `GET {{ api_url }}/v1/users` You can also [fetch details on a single user](/api/get-user). 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: {} 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", "is_admin": false, "is_owner": 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": "vim"}, "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, "role": 400, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com", }, { "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", "is_active": true, "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", "is_admin": false, "is_owner": false, "role": 400, "user_id": 23, "bot_type": 1, "timezone": "", "is_bot": true, }, ], } post: operationId: create_user tags: ["users"] description: | {!can-create-users-only.md!} Create a new user account via the API. `POST {{ api_url }}/v1/users` parameters: - name: email in: query description: | The email address of the new user. schema: type: string example: username@example.com required: true - name: password in: query description: | The password of the new user. schema: type: string example: abcd1234 required: true - name: full_name in: query description: | The full name of the new user. schema: type: string example: New User required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} 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/JsonError" - example: { "msg": "Email 'newbie@zulip.com' already in use", "result": "error", } /users/{user_id}/reactivate: post: operationId: reactivate_user tags: ["users"] description: | {!api-admin-only.md!} [Reactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. `POST {{ api_url }}/v1/users/{user_id}/reactivate` parameters: - $ref: "#/components/parameters/UserId" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} /users/{user_id_or_email}/presence: get: operationId: get_user_presence tags: ["users"] description: | Get the presence status for a specific user. This endpoint is most useful for embedding data about a user's presence status in other sites (E.g. an employee directory). Full Zulip clients like mobile/desktop apps will want to use the main presence endpoint, which returns data for all active users in the organization, instead. `GET {{ api_url }}/v1/users/{user_id_or_email}/presence` See [Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html) for details on the data model for presence in Zulip. parameters: - name: user_id_or_email in: path description: | The user_id or Zulip display 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 display 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: {} presence: type: object description: | An object containing the presence details for every client the user has logged into. 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: | either `active` or `idle`: whether the user had recently interacted with Zulip at the time in the timestamp (this distinguishes orange vs. green dots in the Zulip web UI; orange/idle means we don't know whether the user is actually at their computer or just left the Zulip app open on their desktop). description: | `{client_name}` or `aggregated`: the keys for these objects are the names of the different clients where this user is logged in, like `website`, `ZulipDesktop`, `ZulipTerminal`, or `ZulipMobile`. There is also an `aggregated` key, which matches the contents of the object that has been updated most recently. For most applications, you'll just want to look at the `aggregated` key. example: { "presence": { "website": {"timestamp": 1532697622, "status": "active"}, "ZulipMobile": {"timestamp": 1522687421, "status": "active"}, "aggregated": {"timestamp": 1532697622, "status": "active"}, }, "result": "success", "msg": "", } /users/me: get: operationId: get_own_user tags: ["users"] description: | Get basic data about the user/bot that requests this endpoint. `GET {{ api_url }}/v1/users/me` responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} avatar_url: type: string description: | URL for the user's avatar. **Changes**: New in Zulip 2.1.0. example: "x" 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}`. **Changes**: New in Zulip 3.0 (feature level 10). Previous versions do not return this field. example: 1 email: type: string description: | 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 role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: | [Organization-level role](/help/roles-and-permissions)) of the user. Poosible values are: * Organization owner => 100 * Organization administrator => 200 * Organization moderator => 300 * Member => 400 * Guest => 600 **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). Previous versions do not return this field. 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 user account has been deactivated. **Changes**: New in Zulip 3.0 (feature level 10). Previous versions do not return this field. example: true timezone: type: string description: | The time zone of the user. **Changes**: New in Zulip 3.0 (feature level 10). Previous versions do not return this field. example: "" date_joined: type: string description: | The time the user account was created. **Changes**: New in Zulip 3.0 (feature level 10). Previous versions do not return this field. 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 your 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 user's real email address. This field is present only if [email address visibility](/help/restrict-visibility-of-email-addresses) is limited and you are an administrator with access to real email addresses under the configured policy. 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", "full_name": "Iago", "is_admin": true, "is_owner": false, "role": 200, "is_guest": 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 tags: ["users"] description: | Deactivates the user's account. See also the administrative endpoint for [deactivating another user](/api/deactivate-user). `DELETE {{ api_url }}/v1/users/me` This endpoint is primarily useful to Zulip clients providing a user settings UI. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad Request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "msg": "Cannot deactivate the only organization owner", "result": "error", } /users/me/{stream_id}/topics: get: operationId: get_stream_topics tags: ["streams"] description: | Get all the topics in a specific stream `GET {{ api_url }}/v1/users/me/{stream_id}/topics` parameters: - $ref: "#/components/parameters/StreamIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} topics: type: array description: | An array of `topic` objects. items: type: object additionalProperties: false properties: max_id: description: | The message ID of the last message sent to this topic. type: integer name: description: | The name of the topic. type: string example: { "msg": "", "result": "success", "topics": [ {"max_id": 26, "name": "Denmark3"}, {"max_id": 23, "name": "Denmark1"}, {"max_id": 6, "name": "Denmark2"}, ], } "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Invalid stream id", "result": "error", } /users/me/subscriptions: get: operationId: get_subscriptions tags: ["streams"] description: | Get all streams that the user is subscribed to. `GET {{ api_url }}/v1/users/me/subscriptions` # 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. 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: {} subscriptions: type: array description: | A list of dictionaries where each dictionary contains information about one of the subscribed streams. items: $ref: "#/components/schemas/Subscriptions" example: { "msg": "", "result": "success", "subscriptions": [ { "audible_notifications": true, "color": "#e79ab5", "description": "A Scandinavian country", "desktop_notifications": true, "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", "is_muted": false, "invite_only": false, "name": "Denmark", "pin_to_top": false, "push_notifications": false, "role": 20, "stream_id": 1, "subscribers": [7, 10, 11, 12, 14], }, { "audible_notifications": true, "color": "#e79ab5", "description": "Located in the United Kingdom", "desktop_notifications": true, "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", "is_muted": false, "invite_only": false, "name": "Scotland", "pin_to_top": false, "push_notifications": false, "role": 50, "stream_id": 3, "subscribers": [7, 11, 12, 14], }, ], } post: operationId: subscribe tags: ["streams"] description: | Subscribe one or more users to one or more streams. `POST {{ api_url }}/v1/users/me/subscriptions` If any of the specified streams do not exist, they are automatically created. The initial [stream settings](/api/update-stream) will be determined by the optional parameters like `invite_only` detailed below. parameters: - name: subscriptions in: query description: | A list of dictionaries containing the key `name` and value specifying the name of the stream to subscribe. If the stream does not exist a new stream is created. The description of the stream created can be specified by setting the dictionary key `description` with an appropriate value. content: application/json: schema: type: array items: type: object example: [{"name": "Verona", "description": "Italian city"}] required: true - $ref: "#/components/parameters/Principals" - name: authorization_errors_fatal in: query description: | A boolean specifying whether authorization errors (such as when the requesting user is not authorized to access a private stream) should be considered fatal or not. When `True`, an authorization error is reported as such. When set to `False`, the response will be a 200 and any streams where the request encountered an authorization error will be listed in the `unauthorized` key. schema: type: boolean default: true example: false - name: announce in: query description: | If one of the streams specified did not exist previously and is thus craeted by this call, this determines whether [notification bot](/help/configure-notification-bot) will send an announcement about the new stream's creation. schema: type: boolean default: false example: true - name: invite_only in: query description: | As described above, this endpoint will create a new stream if passed a stream name that doesn't already exist. This parameters and the ones that follow are used to request an initial configuration of a created stream; they are ignored for streams that already exist. This parameter determines whether any newly created streams will be private streams. schema: type: boolean default: false example: true - $ref: "#/components/parameters/HistoryPublicToSubscribers" - $ref: "#/components/parameters/StreamPostPolicy" - $ref: "#/components/parameters/MessageRetentionDays" responses: "200": description: Success. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" - example: { "already_subscribed": {}, "msg": "", "result": "success", "subscribed": {"iago@zulip.com": ["new stream"]}, } - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" - example: { "already_subscribed": {"newbie@zulip.com": ["new stream"]}, "msg": "", "result": "success", "subscribed": {}, } "400": description: Success. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" - example: { "msg": "Unable to access stream (private_stream).", "result": "error", } - allOf: - $ref: "#/components/schemas/AddSubscriptionsResponse" - example: { "already_subscribed": {}, "msg": "", "result": "success", "subscribed": {}, "unauthorized": ["private_stream"], } patch: operationId: update_subscriptions tags: ["streams"] description: | Update which streams you are are subscribed to. parameters: - name: delete in: query description: | A list of stream names to unsubscribe from. content: application/json: schema: type: array items: type: string example: ["Verona", "Denmark"] required: false - name: add in: query description: | A list of objects describing which streams to subscribe to, optionally including per-user subscription parameters (e.g. color) and if the stream is to be created, its description. content: application/json: schema: type: array items: type: object additionalProperties: false properties: name: type: string color: type: string description: type: string example: [ {"name": "Verona"}, { "name": "Denmark", "color": "#e79ab5", "description": "A Scandinavian country", }, ] required: false responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - required: - subscribed - already_subscribed - removed additionalProperties: false properties: result: {} msg: {} subscribed: type: object description: | A dictionary where the key is the email address of the user/bot and the value is a list of the names of the streams that were subscribed to as a result of the query. additionalProperties: description: | `{email_id}`: A list of the names of streams that the user was subscribed to as a result of the query. type: array items: type: string already_subscribed: type: object description: | A dictionary where the key is the email address of the user/bot and the value is a list of the names of the streams that the user/bot is already subscribed to. additionalProperties: description: | `{email_id}`: A list of the names of streams that the user was already subscribed to. type: array items: type: string not_removed: type: array items: type: string description: | A list of the names of streams that the user is already unsubscribed from, and hence doesn't need to be unsubscribed. removed: type: array items: type: string description: | A list of the names of streams which were unsubscribed from as a result of the query. example: { "msg": "", "subscribed": {}, "already_subscribed": {"iago@zulip.com": ["Verona"]}, "not_removed": [], "removed": ["new stream"], "result": "success", } delete: operationId: unsubscribe tags: ["streams"] description: | Unsubscribe yourself or other users from one or more streams. `DELETE {{ api_url }}/v1/users/me/subscriptions` parameters: - name: subscriptions in: query description: | A list of stream names to unsubscribe from. This parameter is called `streams` in our Python API. content: application/json: schema: type: array items: type: string example: ["Verona", "Denmark"] required: true - $ref: "#/components/parameters/Principals" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} not_removed: type: array items: type: string description: | A list of the names of streams that the user is already unsubscribed from, and hence doesn't need to be unsubscribed. removed: type: array items: type: string description: | A list of the names of streams which were unsubscribed from as a result of the query. example: { "msg": "", "not_removed": [], "removed": ["new stream"], "result": "success", } "400": description: Bad request. content: application/json: schema: $ref: "#/components/schemas/NonExistingStreamError" /users/me/subscriptions/muted_topics: patch: operationId: mute_topic tags: ["streams"] description: | This endpoint mutes/unmutes a topic within a stream that the current user is subscribed to. Muted topics are displayed faded in the Zulip UI, and are not included in the user's unread count totals. `PATCH {{ api_url }}/v1/users/me/subscriptions/muted_topics` parameters: - name: stream in: query description: | The name of the stream to access. schema: type: string example: Denmark required: false - name: stream_id in: query description: | The ID of the stream to access. schema: type: integer example: 42 required: false - name: topic in: query description: | The topic to (un)mute. Note that the request will succeed regardless of whether any messages have been sent to the specified topic. schema: type: string example: dinner required: true - name: op in: query description: | Whether to mute (`add`) or unmute (`remove`) the provided topic. schema: type: string enum: - add - remove example: add required: true responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Topic already muted", "result": "error"} - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Topic is not muted", "result": "error"} /users/me/muted_users/{muted_user_id}: post: operationId: mute_user tags: ["users"] description: | This endpoint mutes a user. Messages sent by users you've muted will be automatically marked as read and hidden. `POST {{ api_url }}/v1/users/me/muted_users/{muted_user_id}` 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 your account, which prevents all email and mobile push notifications. * Clients should exclude muted users from presence lists or other UI for viewing or composing 1:1 private messages. 1:1 private messages sent by muted users should be hidden everywhere in the Zulip UI. * Stream messages and group private 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 private message conversations including the muted user should display muted users as "Muted user", rather than showing their name, in lists of such conversations, along with using a blank grey avatar where avatars are displayed. * Administrative/settings UI elements for showing "All users that exist on this stream or realm", e.g. for organization administration or showing stream subscribers, should display the user's name as normal. **Changes**: New in Zulip 4.0 (feature level 48). parameters: - $ref: "#/components/parameters/MutedUserId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Cannot mute self", "result": "error"} - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "No such user", "result": "error"} - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "User already muted", "result": "error"} delete: operationId: unmute_user tags: ["users"] description: | This endpoint unmutes a user. `DELETE {{ api_url }}/v1/users/me/muted_users/{muted_user_id}` **Changes**: New in Zulip 4.0 (feature level 48). parameters: - $ref: "#/components/parameters/MutedUserId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "No such user", "result": "error"} - allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "User is not muted", "result": "error"} /users/{user_id}/subscriptions/{stream_id}: get: operationId: get_subscription_status tags: ["streams"] description: | Check whether a user is subscribed to a stream. `GET {{ api_url }}/v1/users/{user_id}/subscriptions/{stream_id}` **Changes**: New in Zulip 3.0 (feature level 11). parameters: - $ref: "#/components/parameters/UserId" - $ref: "#/components/parameters/StreamIdInPath" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} is_subscribed: type: boolean description: | Whether the user is subscribed to the stream. example: {"msg": "", "result": "success", "is_subscribed": false} /realm/emoji/{emoji_name}: post: operationId: upload_custom_emoji 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/only-allow-admins-to-add-emoji). `POST {{ api_url }}/v1/realm/emoji/{emoji_name}` parameters: - name: emoji_name required: true in: path description: | The name that should be associated with the uploaded emoji image/gif. schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: filename: type: string format: binary example: /path/to/img.png responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" /realm/emoji: get: operationId: get_custom_emoji tags: ["server_and_organizations"] description: | Get all the custom emoji in the user's organization. `GET {{ api_url }}/v1/realm/emoji` responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} 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/profile_fields: get: operationId: get_custom_profile_fields tags: ["server_and_organizations"] description: | Get all the [custom profile fields](/help/add-custom-profile-fields) configured for the user's organization. `GET {{ api_url }}/v1/realm/profile_fields` responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} custom_fields: type: array description: | An array containing all the custom profile fields defined in this Zulip organization. items: $ref: "#/components/schemas/CustomProfileField" example: { "result": "success", "msg": "", "custom_fields": [ { "id": 1, "name": "Phone number", "type": 1, "hint": "", "field_data": "", "order": 1, }, { "id": 2, "name": "Biography", "type": 2, "hint": "What are you known for?", "field_data": "", "order": 2, }, { "id": 3, "name": "Favorite food", "type": 1, "hint": "Or drink, if you'd prefer", "field_data": "", "order": 3, }, { "id": 4, "name": "Favorite editor", "type": 3, "hint": "", "field_data": '{"vim":{"text":"Vim","order":"1"},"emacs":{"text":"Emacs","order":"2"}}', "order": 4, }, { "id": 5, "name": "Birthday", "type": 4, "hint": "", "field_data": "", "order": 5, }, { "id": 6, "name": "Favorite website", "type": 5, "hint": "Or your personal blog's URL", "field_data": "", "order": 6, }, { "id": 7, "name": "Mentor", "type": 6, "hint": "", "field_data": "", "order": 7, }, { "id": 8, "name": "GitHub", "type": 7, "hint": "Enter your GitHub username", "field_data": '{"subtype":"github"}', "order": 8, }, ], } patch: operationId: reorder_custom_profile_fields tags: ["server_and_organizations"] description: | {!api-admin-only.md!} Reorder the custom profile fields in the user's organization. `PATCH {{ api_url }}/v1/realm/profile_fields` 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/add-custom-profile-fields). parameters: - name: order in: query description: | A list of the IDs of all the custom profile fields defined in this organization, in the desired new order. content: application/json: schema: type: array items: type: integer example: [10, 9, 8, 7, 6, 5, 4, 3, 2, 1] required: true responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" post: operationId: create_custom_profile_field tags: ["server_and_organizations"] description: | {!api-admin-only.md!} [Create a custom profile field](/help/add-custom-profile-fields) in the user's organization. `POST {{ api_url }}/v1/realm/profile_fields` parameters: - name: name in: query description: | The name of the custom profile field, which will appear both in user-facing settings UI for configuring custom profile fields and in UI displaying a user's profile. schema: type: string example: "Favorite programming language" - name: hint in: query description: | The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields. schema: type: string example: "Your favorite programming language." - name: field_type in: query description: | The field type can be any of the supported custom profile field types. See the [custom profile fields documentation](/help/add-custom-profile-fields) 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 schema: type: integer example: 3 required: true - name: field_data in: query description: | Field types 3 (List of options) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (List of options), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option. The interface for field type 7 is not yet stabilized. content: application/json: schema: type: object example: { "python": {"text": "Python", "order": "1"}, "java": {"text": "Java", "order": "2"}, } responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} id: type: integer description: | The ID for the custom profile field. example: {"result": "success", "msg": "", "id": 9} /users/me/subscriptions/properties: post: operationId: update_subscription_settings tags: ["streams"] description: | This endpoint is used to update the user's personal settings for the streams they are subscribed to, including muting, color, pinning, and per-stream notification settings. `POST {{ api_url }}/v1/users/me/subscriptions/properties` parameters: - name: subscription_data in: query description: | A list of objects that describe the changes that should be applied in each subscription. Each object represents a subscription, and must have a `stream_id` key that identifies the stream, as well as the `property` being modified and its new `value`. The possible values for each `property` and `value` pairs are: * `color` (string): the hex value of the user's display color for the stream. * `is_muted` (boolean): whether the stream is [muted](/help/mute-a-stream). Prior to Zulip 2.1, this feature was represented by the more confusingly named `in_home_view` (with the opposite value, `in_home_view=!is_muted`); for backwards-compatibility, modern Zulip still accepts that value. * `pin_to_top` (boolean): whether to pin the stream at the top of the stream list. * `desktop_notifications` (boolean): whether to show desktop notifications for all messages sent to the stream. * `audible_notifications` (boolean): whether to play a sound notification for all messages sent to the stream. * `push_notifications` (boolean): whether to trigger a mobile push notification for all messages sent to the stream. * `email_notifications` (boolean): whether to trigger an email notification for all messages sent to the stream. content: application/json: schema: type: array items: type: object example: [ {"stream_id": 1, "property": "pin_to_top", "value": true}, {"stream_id": 3, "property": "color", "value": "#f00f00"}, ] required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} subscription_data: type: array items: type: object additionalProperties: false properties: property: type: string description: | The property to be changed. It is one of: * `color`: The hex value of the user's personal display color for the stream.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, "role": 400, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com", }, } /users/{user_id}: get: operationId: get_user tags: ["users"] description: | Fetch details for a single user in the organization. `GET {{ api_url }}/v1/users/{user_id}` You can also fetch details on [all users in the organization](/api/get-users) or [by email](/api/get-user-by-email). *This endpoint is new in Zulip Server 3.0 (feature level 1).* 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: {} 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": "vim"}, "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, "role": 400, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com", }, } patch: operationId: update_user tags: ["users"] description: | {!api-admin-only.md!} Administrative endpoint to update the details of another user in the organization. `PATCH {{ api_url }}/v1/users/{user_id}` 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/add-custom-profile-fields). parameters: - $ref: "#/components/parameters/UserId" - name: full_name in: query description: | The user's full name. content: application/json: schema: type: string example: NewName required: false - name: role in: query description: | New [role](/help/roles-and-permissions) for the user. Roles are encoded as: * Organization owner: 100 * Organization administrator: 200 * Organization moderator: 300 * Member: 400 * Guest: 600 Only organization owners can add or remove the owner role. The owner role cannot be removed from the only organization owner. **Changes**: New in Zulip 3.0 (feature level 8), replacing the previous pair of `is_admin` and `is_guest` boolean parameters. Organization moderator role added in Zulip 4.0 (feature level 60). schema: type: integer example: 400 required: false - name: profile_data in: query description: | A dictionary containing the to be updated custom profile field data for the user. content: application/json: schema: type: array items: type: object example: [{"id": 4, "value": "vim"}, {"id": 5, "value": "1909-04-05"}] required: false responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/CodedError" - example: { "result": "error", "msg": "Guests cannot be organization administrators", "code": "BAD_REQUEST", } delete: operationId: deactivate_user tags: ["users"] description: | {!api-admin-only.md!} [Deactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. `DELETE {{ api_url }}/v1/users/{user_id}` parameters: - $ref: "#/components/parameters/UserId" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad Request content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "msg": "Cannot deactivate the only organization owner", "result": "error", } /realm/linkifiers: get: operationId: 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. `GET {{ api_url }}/v1/realm/linkifiers` **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: {} linkifiers: type: array description: | An array of objects, where each object describes a linkifier. 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_format: type: string description: | The URL format string to be used for linkifying matches. id: type: integer description: | The ID of the linkifier. example: { "msg": "", "linkifiers": [ { "pattern": "#(?PThe Zulip development environment default organization. It's great for testing!
", "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/landing-page/logos/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/landing-page/logos/github-icon.png", "login_url": "/accounts/login/social/github", "signup_url": "/accounts/register/social/github", }, ], } /settings/notifications: patch: operationId: update_notification_settings tags: ["users"] description: | This endpoint is used to edit the user's global notification settings. See [this endpoint](/api/update-subscription-settings) for per-stream notification settings. `PATCH {{ api_url }}/v1/settings/notifications` parameters: - name: enable_stream_desktop_notifications in: query description: | Enable visual desktop notifications for stream messages. schema: type: boolean example: true - name: enable_stream_email_notifications in: query description: | Enable email notifications for stream messages. schema: type: boolean example: true - name: enable_stream_push_notifications in: query description: | Enable mobile notifications for stream messages. schema: type: boolean example: true - name: enable_stream_audible_notifications in: query description: | Enable audible desktop notifications for stream messages. schema: type: boolean example: true - name: notification_sound in: query description: | Notification sound name. content: application/json: schema: type: string example: ding - name: enable_desktop_notifications in: query description: | Enable visual desktop notifications for private messages and @-mentions. schema: type: boolean example: true - name: enable_sounds in: query description: | Enable audible desktop notifications for private messages and @-mentions. schema: type: boolean example: true - name: enable_offline_email_notifications in: query description: | Enable email notifications for private messages and @-mentions received when the user is offline. schema: type: boolean example: true - name: enable_offline_push_notifications in: query description: | Enable mobile notification for private messages and @-mentions received when the user is offline. schema: type: boolean example: true - name: enable_online_push_notifications in: query description: | Enable mobile notification for private messages and @-mentions received when the user is online. schema: type: boolean example: true - name: enable_digest_emails in: query description: | Enable digest emails when the user is away. schema: type: boolean example: true - name: enable_marketing_emails in: query description: | Enable marketing emails. Has no function outside Zulip Cloud. schema: type: boolean example: true - name: enable_login_emails in: query description: | Enable email notifications for new logins to account. schema: type: boolean example: true - name: message_content_in_email_notifications in: query description: | Include the message's content in email notifications for new messages. schema: type: boolean example: true - name: pm_content_in_desktop_notifications in: query description: | Include content of private messages in desktop notifications. schema: type: boolean example: true - name: wildcard_mentions_notify in: query description: | Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. schema: type: boolean example: true - name: desktop_icon_count_display in: query description: | Unread count summary (appears in desktop sidebar and browser tab) * 1 - All unreads * 2 - Private messages and mentions * 3 - None content: application/json: schema: type: integer enum: - 1 - 2 - 3 example: 1 - name: realm_name_in_notifications in: query description: | Include organization name in subject of message notification emails. schema: type: boolean example: true - name: presence_enabled in: query description: | Display the presence status to other users when online. schema: type: boolean example: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} enable_desktop_notifications: type: boolean description: | The setting for `enable_desktop_notifications`, if it was changed in this request. enable_digest_emails: type: boolean description: | The setting for `enable_digest_emails`, if it was changed in this request. enable_marketing_emails: type: boolean description: | The setting for `enable_marketing_emails`, if it was changed in this request. enable_offline_email_notifications: type: boolean description: | The setting for `enable_offline_email_notifications`, if it was changed in this request. enable_offline_push_notifications: type: boolean description: | The setting for `enable_offline_push_notifications`, if it was changed in this request. enable_online_push_notifications: type: boolean description: | The setting for `enable_online_push_notifications`, if it was changed in this request. enable_sounds: type: boolean description: | The setting for `enable_sounds`, if it was changed in this request. enable_stream_email_notifications: type: boolean description: | The setting for `enable_stream_email_notifications`, if it was changed in this request. enable_stream_push_notifications: type: boolean description: | The setting for `enable_stream_push_notifications`, if it was changed in this request. enable_stream_audible_notifications: type: boolean description: | The setting for `enable_stream_audible_notifications`, if it was changed in this request. message_content_in_email_notifications: type: boolean description: | The setting for `message_content_in_email_notifications`, if it was changed in this request. example: { "enable_offline_push_notifications": true, "enable_online_push_notifications": true, "msg": "", "result": "success", } /settings/display: patch: operationId: update_display_settings tags: ["users"] description: | This endpoint is used to edit the current user's user interface settings. `PATCH {{ api_url }}/v1/settings/display` parameters: - name: twenty_four_hour_time in: query description: | Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). schema: type: boolean example: true - name: dense_mode in: query description: | This setting has no effect at present. It is reserved for use in controlling the default font size in Zulip. schema: type: boolean example: true - name: starred_message_counts in: query description: | Whether clients should display the [number of starred messages](/help/star-a-message#display-the-number-of-starred-messages). schema: type: boolean example: true - name: fluid_layout_width in: query description: | Whether to use the [maximum available screen width](/help/enable-full-width-display) for the webapp's center panel (message feed, recent topics) on wide screens. schema: type: boolean example: true - name: high_contrast_mode in: query description: | This setting is reserved for use to control variations in Zulip's design to help visually impaired users. schema: type: boolean example: true - name: color_scheme in: query description: | Controls which [color theme](/help/night-mode) to use. * 1 - Automatic * 2 - Night mode * 3 - Day mode Automatic detection is implementing using the standard `prefers-color-scheme` media query. content: application/json: schema: type: integer enum: - 1 - 2 - 3 example: 1 - name: translate_emoticons in: query description: | Whether to [translate emoticons to emoji](/help/enable-emoticon-translations) in messages the user sends. schema: type: boolean example: true - name: default_language in: query description: | What [default language](/help/change-your-language) to use for the account. This controls both the Zulip UI as well as email notifications sent to the user. The value needs to be a standard language code that the Zulip server has translation data for; for example, `"en"` for English` or `"de"` for German. content: application/json: schema: type: string example: "en" - name: default_view in: query description: | The [default view](/help/change-default-view) used when opening a new Zulip webapp window or hitting the `Esc` keyboard shortcut repeatedly. * "recent_topics" - Recent topics view * "all_messages" - All messages view schema: type: string example: '"all_messages"' - name: left_side_userlist in: query description: | Whether the users list on left sidebar in narrow windows. This feature is not heavily used and is likely to be reworked. schema: type: boolean example: true - name: emojiset in: query description: | The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons), used to display emoji to the user everything they appear in the UI. * "google" - Google modern * "google-blob" - Google classic * "twitter" - Twitter * "text" - Plain text schema: type: string example: '"google"' - name: demote_inactive_streams in: query description: | Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar. * 1 - Automatic * 2 - Always * 3 - Never content: application/json: schema: type: integer enum: - 1 - 2 - 3 example: 1 - name: timezone in: query description: | The user's [configured timezone](/help/change-your-timezone). Timezone values supported by the server are served at [/static/generated/timezones.json](/static/generated/timezones.json). content: application/json: schema: type: string example: "Asia/Kolkata" responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} twenty_four_hour_time: type: boolean description: | The setting for `twenty_four_hour_time`, if it was changed in this request. dense_mode: type: boolean description: | The setting for `dense_mode`, if it was changed in this request. This setting is however reserved for future, and can not be modified in production environment. starred_message_counts: type: boolean description: | The setting for `starred_message_counts`, if it was changed in this request. fluid_layout_width: type: boolean description: | The setting for `fluid_layout_width`, if it was changed in this request. high_contrast_mode: type: boolean description: | The setting for `high_contrast_mode`, if it was changed in this request. This setting is however reserved for future, and can not be modified in production environment. color_scheme: type: integer description: | The numerical key corresponding to new `color_scheme` if it was changed in this request. translate_emoticons: type: boolean description: | The setting for `translate_emoticons`, if it was changed in this request. default_language: type: string description: | The language code corresponding to new `default_language` if it was changed in this request. default_view: type: string description: | The new setting for `default_view`, if it was changed in this request. left_side_userlist: type: boolean description: | The setting for `left_side_userlist`, if it was changed in this request. emojiset: type: string description: | The string identifier corresponding to new `emojiset` if it was changed in this request. demote_inactive_streams: type: integer description: | The numerical key corresponding to new `demote_inactive_streams` setting if it was changed in this request. timezone: type: string description: | The setting for `timezone`, if it was changed in this request. example: { "emojiset": "google", "left_side_userlist": true, "msg": "", "result": "success", } /streams: get: operationId: get_streams tags: ["streams"] description: | Get all streams that the user has access to. `GET {{ api_url }}/v1/streams` parameters: - name: include_public in: query description: | Include all public streams. schema: type: boolean default: true example: false - name: include_web_public in: query description: | Include all web public streams. schema: type: boolean default: false example: true - name: include_subscribed in: query description: | Include all streams that the user is subscribed to. schema: type: boolean default: true example: false - name: include_all_active in: query description: | Include all active streams. The user must have administrative privileges to use this parameter. schema: type: boolean default: false example: true - name: include_default in: query description: | Include all default streams for the user's realm. schema: type: boolean default: false example: true - name: include_owner_subscribed in: query description: | If the user is a bot, include all streams that the bot's owner is subscribed to. schema: type: boolean default: false example: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} streams: description: | A list of `stream` objects with details on the requested streams. type: array items: allOf: - $ref: "#/components/schemas/BasicStreamBase" - additionalProperties: false properties: stream_id: {} name: {} description: {} date_created: {} invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: {} history_public_to_subscribers: {} first_message_id: {} is_announcement_only: {} is_default: type: boolean description: | Whether the given stream is a [default stream](/help/set-default-streams-for-new-users). Only returned if the `include_default` parameter is `true`. example: { "msg": "", "result": "success", "streams": [ { "description": "A Scandinavian country", "invite_only": false, "name": "Denmark", "stream_id": 1, }, { "description": "Yet another Italian city", "invite_only": false, "name": "Rome", "stream_id": 2, }, { "description": "Located in the United Kingdom", "invite_only": false, "name": "Scotland", "stream_id": 3, }, { "description": "A northeastern Italian city", "invite_only": false, "name": "Venice", "stream_id": 4, }, { "description": "A city in Italy", "invite_only": false, "name": "Verona", "stream_id": 5, }, { "description": "New stream for testing", "invite_only": false, "name": "new stream", "stream_id": 6, }, ], } "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", } /streams/{stream_id}: delete: operationId: archive_stream tags: ["streams"] description: | [Archive the stream](/help/archive-a-stream) with the ID `stream_id`. `DELETE {{ api_url }}/v1/streams/{stream_id}` parameters: - $ref: "#/components/parameters/StreamIdInPath" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Invalid stream id", "result": "error", } patch: operationId: update_stream tags: ["streams"] description: | Configure the stream with the ID `stream_id`. This endpoint supports an organization administrator editing any property of a stream, including: * Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description) * Stream [permissions](/help/stream-permissions), including [privacy](/help/change-the-privacy-of-a-stream) and [who can send](/help/stream-sending-policy). `PATCH {{ api_url }}/v1/streams/{stream_id}` parameters: - $ref: "#/components/parameters/StreamIdInPath" - name: description in: query description: | The new description for the stream. content: application/json: schema: type: string example: This stream is related to football dicsussions. required: false - name: new_name in: query description: | The new name for the stream. content: application/json: schema: type: string example: Italy required: false - name: is_private in: query description: | Change whether the stream is a private stream. schema: type: boolean example: true required: false - name: is_announcement_only in: query deprecated: true description: | Whether the stream is limited to announcements. **Changes**: Deprecated in Zulip 3.0 (feature level 1), use `stream_post_policy` instead. schema: type: boolean example: true required: false - $ref: "#/components/parameters/StreamPostPolicy" - $ref: "#/components/parameters/HistoryPublicToSubscribers" - $ref: "#/components/parameters/MessageRetentionDays" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Invalid stream id", "result": "error", } /typing: post: operationId: set_typing_status tags: ["users"] description: | Notify other users whether the current user is typing a message. `POST {{ api_url }}/v1/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 typing a message, and also every `TYPING_STARTED_WAIT_PERIOD=10` seconds that the user continues to actively type or otherwise interact with the compose UI (E.g. interacting with the compose box emoji picker). * Send a request to this endpoint with `op="stop"` when a user pauses using the compose UI for at least `TYPING_STOPPED_WAIT_PERIOD=5` seconds or cancels the compose action (if it had previously sent a "start" operation for that compose action). * Start displaying "Sender is typing" for a given conversation when the client receives an `op="start"` event from the [events API](/api/get-events). * Continue displaying "Sender is typing" until they receive an `op="stop"` event from the [events API](/api/get-events) or `TYPING_STARTED_EXPIRY_PERIOD=15` seconds have passed without a new `op="start"` event for that conversation. * Clients that support displaying stream typing notifications (new in Zulip 4.0) should indicate they support processing stream typing events via the `stream_typing_notifications` in the `client_capabilities` parameter to `/register`. This protocol is designed to allow the server-side typing notifications implementation to be stateless while being resilient; network failures cannot result in a user being incorrectly displayed as perpetually typing. See [the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html) for additional design details on Zulip's typing notifications protocol. parameters: - name: type in: query description: | Type of the message being composed. schema: type: string enum: - private - stream default: private example: private - name: op in: query description: | Whether the user has started (`start`) or stopped (`stop`) to type. schema: type: string enum: - start - stop example: start required: true - name: to in: query description: | For 'private' type it is the user_ids of the recipients of the message being typed. Send a JSON-encoded list of user_ids. (Use a list even if there is only one recipient.) For 'stream' type it is a single element list containing ID of stream in which the message being typed. **Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded list of email addresses. Support for the email address-based format was removed in Zulip 3.0 (feature level 11). content: application/json: schema: type: array items: type: integer example: [9, 10] - name: topic in: query description: | Topic to which message is being typed. Required for the 'stream' type. Ignored in case of 'private' type. schema: type: string example: typing notifications responses: "200": description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Cannot send to multiple streams", "result": "error", } /user_groups/create: post: operationId: create_user_group tags: ["users"] description: | Create a new [user group](/help/user-groups). `POST {{ api_url }}/v1/user_groups/create` parameters: - name: name in: query description: | The name of the user group. schema: type: string example: marketing required: true - name: description in: query description: | The description of the user group. schema: type: string example: The marketing team. required: true - name: members in: query description: | An array containing the user IDs of the initial members for the new user group. content: application/json: schema: type: array items: type: integer example: [1, 2, 3, 4] required: true responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"msg": "", "result": "success"} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "result": "error", "code": "BAD_REQUEST", "msg": "Invalid user ID: 500", } /user_groups/{user_group_id}/members: post: operationId: update_user_group_members tags: ["users"] description: | Update the members of a [user group](/help/user-groups). `POST {{ api_url }}/v1/user_groups/{user_group_id}/members` parameters: - $ref: "#/components/parameters/UserGroupId" - name: delete in: query description: | The list of user ids to be removed from the user group. content: application/json: schema: type: array items: type: integer example: [10] required: false - name: add in: query description: | The list of user ids to be added to the user group. content: application/json: schema: type: array items: type: integer example: [12, 13] required: false responses: "200": $ref: "#/components/responses/SimpleSuccess" /user_groups/{user_group_id}: patch: operationId: update_user_group tags: ["users"] description: | Update the name or description of a [user group](/help/user-groups). `PATCH {{ api_url }}/v1/user_groups/{user_group_id}` parameters: - $ref: "#/components/parameters/UserGroupId" - name: name in: query description: | The new name of the group. schema: type: string example: marketing team required: true - name: description in: query description: | The new description of the group. schema: type: string example: The marketing team. required: true responses: "200": $ref: "#/components/responses/SimpleSuccess" "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Invalid user group", "result": "error", } delete: operationId: remove_user_group tags: ["users"] description: | Delete a [user group](/help/user-groups). `DELETE {{ api_url }}/v1/user_groups/{user_group_id}` parameters: - $ref: "#/components/parameters/UserGroupId" responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccess" - example: {"result": "success", "msg": ""} "400": description: Bad request. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonError" - example: { "code": "BAD_REQUEST", "msg": "Invalid user group", "result": "error", } /user_groups: get: operationId: get_user_groups tags: ["users"] description: | Fetches all of the user groups in the organization. `GET {{ api_url }}/v1/user_groups` responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} user_groups: type: array items: type: object additionalProperties: false properties: description: type: string description: | The human-readable description of the user group. id: type: integer description: | The user group's integer id. members: type: array description: | The integer user IDs of the user group members. items: type: integer name: type: string description: | User group name. description: | A list of `user_group` objects, which contain a `description`, a `name`, their `id` and the list of members of the user group. example: { "msg": "", "result": "success", "user_groups": [ { "description": "Characters of Hamlet", "id": 1, "name": "hamletcharacters", "members": [3, 4], }, { "description": "Other users", "id": 2, "name": "other users", "members": [1, 2], }, ], } /real-time: # This entry is a hack; it exists to give us a place to put the text # documenting the parameters for call_on_each_event and friends. post: tags: ["real_time_events"] description: | (Ignored) parameters: - $ref: "#/components/parameters/Event_types" - $ref: "#/components/parameters/Narrow" - $ref: "#/components/parameters/AllPublicStreams" security: - basicAuth: [] responses: # Makeshift response for this hack entry. "200": description: Success /rest-error-handling: post: operationId: rest_error_handling tags: ["real_time_events"] description: | Common error to many endpoints responses: "400": description: | Bad request. content: application/json: schema: oneOf: - $ref: "#/components/schemas/InvalidApiKeyError" - $ref: "#/components/schemas/MissingArgumentError" - $ref: "#/components/schemas/UserNotAuthorizedError" "403": description: | Forbidden content: application/json: schema: oneOf: - $ref: "#/components/schemas/UserDeactivatedError" - $ref: "#/components/schemas/RealmDeactivatedError" /zulip-outgoing-webhook: post: operationId: zulip_outgoing_webhooks tags: ["webhooks"] description: | Outgoing webhooks allows 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 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 `private_message` and `mention`. 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 dict 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: {} client: {} content: {} content_type: {} display_recipient: {} id: {} is_me_message: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} topic_links: {} submessages: {} timestamp: {} 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: ["streams"] operationId: create_big_blue_button_video_call description: | Create a video call URL for a Big Blue Button video call. Requires Big Blue Button to be configured on the Zulip server. responses: "200": description: Success. content: application/json: schema: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} url: description: | The URL for the Big Blue Button video call. type: string example: "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" example: { "msg": "", "result": "success", "url": "/calls/bbb/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: 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). 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 2.2 (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 2.2 (feature level 22). This field was previously strangely called `name` and was a floating point number. id: type: integer description: | The unique message ID. Messages should always be displayed sorted by ID. BasicStream: allOf: - $ref: "#/components/schemas/BasicStreamBase" - additionalProperties: false properties: stream_id: {} name: {} description: {} date_created: {} invite_only: {} rendered_description: {} is_web_public: {} stream_post_policy: {} message_retention_days: {} history_public_to_subscribers: {} first_message_id: {} is_announcement_only: {} BasicStreamBase: type: object description: | Object containing basic details about the stream. additionalProperties: false properties: stream_id: type: integer description: | The unique ID of the stream. name: type: string description: | The name of the stream. description: type: string description: | The short description of the stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description. date_created: type: integer description: | The UNIX timestamp for when the stream was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). invite_only: type: boolean description: | Specifies whether the stream is private or not. Only people who have been invited can access a private stream. rendered_description: type: string description: | The short description of the stream rendered as HTML, intended to be used when displaying the stream description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. is_web_public: type: boolean description: | Whether the stream has been configured to allow unauthenticated access to its message history from the web. stream_post_policy: type: integer description: | Policy for which users can post messages to the stream. * 1 => Any user can post. * 2 => Only administrators can post. * 3 => Only full members can post. * 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. message_retention_days: type: integer nullable: true description: | Number of days that messages sent to this stream will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). There are two special values: * `null`, the default, means the stream will inherit the organization level setting. * `-1` encodes retaining messages in this stream forever. **Changes**: New in Zulip 3.0 (feature level 17). history_public_to_subscribers: type: boolean description: | Whether the history of the stream is public to its subscribers. Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future. first_message_id: type: integer nullable: true description: | The id of the first message in the stream. Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed. Null is used for streams with no message history. is_announcement_only: type: boolean deprecated: true description: | Whether the given stream is announcement only or not. **Changes**: Deprecated in Zulip 3.0 (feature level 1), use `stream_post_policy` instead. BasicBot: allOf: - $ref: "#/components/schemas/BasicBotBase" - additionalProperties: false properties: user_id: {} full_name: {} api_key: {} default_sending_stream: {} default_events_register_stream: {} default_all_public_streams: {} avatar_url: {} owner_id: {} services: {} BasicBotBase: type: object properties: user_id: type: integer description: | The user id of the bot. full_name: type: string description: | The full name of the bot. api_key: type: string description: | The API key of the bot which it uses to make API requests. default_sending_stream: type: string nullable: true description: | The default sending stream of the bot. Null if the bot doesn't have a default sending stream. default_events_register_stream: type: string nullable: true description: | The default stream for which the bot receives events/register data. Null if the bot doesn't have such a default stream. default_all_public_streams: type: boolean description: | Whether the bot can send messages to all streams by default. avatar_url: type: string description: | The URL of the bot's avatar. owner_id: type: integer nullable: true description: | The user id of the bot's owner. Null if the bot has no owner. services: type: array description: | The "Services" array contains extra configuration fields only relevant for Outgoing webhook bots and Embedded bots. It is always a single-element array. We consider this part of the Zulip API to be unstable; it is used only for UI elements for administering bots and is likely to change. items: description: | Object containing details extra details. Which fields appear depend on the type of bot. oneOf: - type: object additionalProperties: false description: | When the bot is an outgoing webhook bot. properties: base_url: type: string description: | The URL the outgoing webhook is configured to post to. token: type: string description: | A unique token that the third-party service can use to confirm that the request is indeed coming from Zulip. interface: type: integer description: | Integer indicating what format requests are posted in: * 1 = Zulip's native outgoing webhook format. * 2 = Emulate the Slack outgoing webhook format. - type: object additionalProperties: false description: | When the bot is an embedded bot. properties: service_name: type: string description: | The name of the bot. config_data: $ref: "#/components/schemas/Config" Bot: allOf: - $ref: "#/components/schemas/BasicBotBase" - description: | Object containing details of a bot. additionalProperties: false properties: user_id: {} full_name: {} api_key: {} default_sending_stream: {} default_events_register_stream: {} default_all_public_streams: {} avatar_url: {} owner_id: {} services: {} email: type: string description: | The email of the bot. bot_type: type: integer nullable: true description: | An integer describing the type of bot: * `1` for a `Generic` bot. * `2` for an `Incoming webhook` bot. * `3` for an `Outgoing webhook` bot. * `4` for an `Embedded` bot. is_active: type: boolean description: | A boolean describing whether the user account has been deactivated. Config: type: object description: | A "string: string" dictionary which describes the configuration for the embedded bot (usually details like API keys). additionalProperties: description: | String describing the config data. type: string CustomProfileField: type: object additionalProperties: false description: | Dictionary containing the details of a custom profile field configured for this organization. properties: id: type: integer description: | The ID of the custom profile field. This will be referenced in custom the 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 [Add custom profile fields](/help/add-custom-profile-fields) 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 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. Hotspot: type: object additionalProperties: false description: | Dictionary containing details of a single hotspot. properties: delay: type: number description: | The delay after which the user should be shown the hotspot. name: type: string description: | The name of the hotspot. title: type: string description: | The title of the hotspot, as will be displayed to the user. description: type: string description: | The description of the hotspot, as will be displayed to the user. 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. 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 and `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_prefix: type: string description: | The url prefix for the playground. RealmExport: type: object additionalProperties: false description: | Object containing details about a realm export. properties: id: type: integer description: | The id of the export. acting_user_id: type: integer description: | The id of the user who did the export. export_time: type: number description: | The UNIX timestamp of when the export was made. deleted_timestamp: type: number nullable: true description: | The timestamp of when the export was deleted. Null if it wasn't. failed_timestamp: type: number nullable: true description: | The timestamp of when the export failed. Null if it didn't. export_url: type: string nullable: true description: | The URL of the export. `null` if there's no URL. pending: type: boolean description: | Whether the export is pending or not. UserGroup: type: object additionalProperties: false description: | Object containing the user group's attributes. properties: name: type: string description: | The name of the user group. description: type: string description: | The description of the user group. members: type: array items: type: integer description: | Array containing the id of the users who are members of this user group. id: type: integer description: | The ID of the user group. Subscriptions: type: object additionalProperties: false properties: stream_id: type: integer description: | The unique ID of a stream. name: type: string description: | The name of a stream. description: type: string description: | The short description of a stream in text/markdown format, intended to be used to prepopulate UI for editing a stream's description. rendered_description: type: string description: | A short description of a stream rendered as HTML, intended to be used when displaying the stream description in a UI. One should use the standard Zulip rendered_markdown CSS when displaying this content so that emoji, LaTeX, and other syntax work correctly. And any client-side security logic for user-generated message content should be applied when displaying this HTML as though it were the body of a Zulip message. date_created: type: integer description: | The UNIX timestamp for when the stream was created, in UTC seconds. **Changes**: New in Zulip 4.0 (feature level 30). invite_only: type: boolean description: | Specifies whether the stream is private or not. Only people who have been invited can access a private stream. # TODO: This subscribers item should probably be declared optional more # explicitly in the OpenAPI format? subscribers: type: array items: type: integer description: | A list of user IDs of users who are also subscribed to a given stream. Included only if `include_subscribers` is `true`. desktop_notifications: type: boolean nullable: true description: | A boolean specifying whether desktop notifications are enabled for the given stream. A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_desktop_notifications, for this stream. email_notifications: type: boolean nullable: true description: | A boolean specifying whether email notifications are enabled for the given stream. A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_email_notifications, for this stream. wildcard_mentions_notify: type: boolean nullable: true description: | A boolean specifying whether wildcard mentions trigger notifications as though they were personal mentions in this stream. A null value means the value of this setting should be inherited from the user-level default setting, wildcard_mentions_notify, for this stream. push_notifications: type: boolean nullable: true description: | A boolean specifying whether push notifications are enabled for the given stream. A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_push_notifications, for this stream. audible_notifications: type: boolean nullable: true description: | A boolean specifying whether audible notifications are enabled for the given stream. A null value means the value of this setting should be inherited from the user-level default setting, enable_stream_audible_notifications, for this stream. pin_to_top: type: boolean description: | A boolean specifying whether the given stream has been pinned to the top. email_address: type: string description: | Email address of the given stream, used for [sending emails to the stream](/help/message-a-stream-by-email). is_muted: type: boolean description: | Whether the user has muted the stream. Muted streams do not count towards your total unread count and do not show up in `All messages` view (previously known as `Home` view). **Changes**: Prior to Zulip 2.1, this feature was represented by the more confusingly named `in_home_view` (with the opposite value, `in_home_view=!is_muted`). in_home_view: type: boolean deprecated: true description: | Legacy property for if the given stream is muted, with inverted meeting. **Deprecated**; clients should use is_muted where available. is_announcement_only: type: boolean deprecated: true description: | Whether only organization administrators can post to the stream. **Changes**: Deprecated in Zulip 3.0 (feature level 1), use `stream_post_policy` instead. is_web_public: type: boolean description: | Whether the stream has been configured to allow unauthenticated access to its message history from the web. role: type: integer enum: - 20 - 50 description: | The user's role within the stream (distinct from the user's [organization-level role](/help/roles-and-permissions)). Valid values are: * 20 => Stream administrator. * 50 => Subscriber. **Changes**: New in Zulip 4.0 (feature level 31). color: type: string description: | The user's personal color for the stream. stream_post_policy: type: integer description: | Policy for which users can post messages to the stream. * 1 => Any user can post. * 2 => Only administrators can post. * 3 => Only full members can post. * 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. message_retention_days: type: integer nullable: true description: | Number of days that messages sent to this stream will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). There are two special values: * `null`, the default, means the stream will inherit the organization level setting. * `-1` encodes retaining messages in this stream forever. **Changes**: New in Zulip 3.0 (feature level 17). history_public_to_subscribers: type: boolean description: | Whether the history of the stream is public to its subscribers. Currently always true for public streams (i.e. invite_only=False implies history_public_to_subscribers=True), but clients should not make that assumption, as we may change that behavior in the future. first_message_id: type: integer nullable: true description: | The id of the first message in the stream. Intended to help clients determine whether they need to display UI like the "more topics" widget that would suggest the stream has older history that can be accessed. Null is used for streams with no message history. stream_weekly_traffic: type: integer nullable: true description: | The average number of messages sent to the stream in recent weeks, rounded to the nearest integer. Null means the stream was recently created and there is insufficient data to estimate the average traffic. DefaultStreamGroup: type: object description: | Dictionary containing details of a default stream group. additionalProperties: false properties: name: type: string description: | Name of the default stream group. description: type: string description: | Description of the default stream group. id: type: integer description: | id of the default stream group. streams: type: array description: | Array containing details about the streams in the default stream group. items: $ref: "#/components/schemas/BasicStream" EmojiReaction: allOf: - $ref: "#/components/schemas/EmojiReactionBase" - additionalProperties: false properties: emoji_code: {} emoji_name: {} reaction_type: {} user_id: {} user: {} EmojiReactionBase: type: object properties: emoji_code: type: string description: | A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. For example, for `unicode_emoji`, this will be an encoding of the Unicode codepoint. emoji_name: type: string description: | Name of the emoji. reaction_type: type: string description: | One of the following values: * `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode codepoint). * `realm_emoji`: [Custom emoji](/help/add-custom-emoji). (`emoji_code` will be its ID). * `zulip_extra_emoji`: Special emoji included with Zulip. Exists to namespace the `zulip` emoji. 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**: In the [events API](/api/get-events), this `user` dictionary confusing had the user ID in a field called `user_id` instead. We recommend ignoring fields other than the user ID. **Deprecated** and to be removed in a future release once core clients have migrated to use the `user_id` field. properties: id: type: integer description: | ID of the user. email: type: string description: | 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. Messages: allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: {} client: {} content: {} content_type: {} display_recipient: {} id: {} is_me_message: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} topic_links: {} submessages: {} timestamp: {} type: {} MessagesBase: type: object description: | Object containing details of the message. properties: avatar_url: type: string nullable: true description: | The URL of the user's avatar. Can be null only if client_gravatar was passed, which means that the user has not uploaded an avatar in Zulip, and the client should compute the gravatar URL by hashing the user's email address itself for this user. 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: | Email of the user. full_name: type: string description: | Full name of the user. is_mirror_dummy: type: boolean description: | Whether the user is a mirror dummy. description: | Data on the recipient of the message; either the name of a stream or a dictionary containing basic data on the users who received the message. 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 reactions: type: array description: | Data on any reactions to the message. items: $ref: "#/components/schemas/EmojiReaction" recipient_id: type: integer description: | A unique ID for the set of users receiving the message (either a stream or group of users). Useful primarily for hashing. sender_email: type: string description: | The Zulip display email address of the message's sender. sender_full_name: type: string description: | The full name of the message's sender. sender_id: type: integer description: | The user ID of the message's sender. sender_realm_str: type: string description: | A string identifier for the realm the sender is in. Unique only within the context of a given Zulip server. E.g. on `example.zulip.com`, this will be `example`. stream_id: type: integer description: | Only present for stream messages; the ID of the stream. subject: type: string description: | The `topic` of the message. Currently always `""` for private messages, though this could change if Zulip adds support for topics in private message conversations. The field name is a legacy holdover from when topics were called "subjects" and will eventually change. 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. submessages: type: array items: type: string description: | Data used for certain experimental Zulip integrations. timestamp: type: integer description: | The UNIX timestamp for when the message was sent, in UTC seconds. type: type: string description: | The type of the message: `stream` or `private`. GetMessages: allOf: - $ref: "#/components/schemas/MessagesBase" - additionalProperties: false properties: avatar_url: {} client: {} content: {} content_type: {} display_recipient: {} id: {} is_me_message: {} reactions: {} recipient_id: {} sender_email: {} sender_full_name: {} sender_id: {} sender_realm_str: {} stream_id: {} subject: {} topic_links: {} submessages: {} timestamp: {} type: {} flags: type: array description: | The user's [message flags][message-flags] for the message. [message-flags]: /api/update-message-flags#available-flags items: type: string last_edit_timestamp: type: integer description: | The UNIX timestamp for when the message was last edited, in UTC seconds. 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. Presence: type: object description: | `{client_name}`: Object containing the details of the user's presence on a particular platform with the client's platform name being the object key. additionalProperties: false properties: client: type: string description: | The client's platform name. status: type: string enum: - idle - active description: | The status of the user on this client. It is 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. User: allOf: - $ref: "#/components/schemas/UserBase" - additionalProperties: false properties: email: {} is_bot: {} avatar_url: {} avatar_version: {} full_name: {} is_admin: {} is_owner: {} role: {} bot_type: {} user_id: {} bot_owner_id: {} is_active: {} is_guest: {} timezone: {} date_joined: {} delivery_email: {} profile_data: {} UserBase: type: object description: | A dictionary containing basic data on a given Zulip user. properties: 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. is_bot: type: boolean description: | A boolean specifying whether the user is a bot or full account. 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` and the user's avatar is hosted by the Gravatar provider (i.e. the user has never uploaded an avatar). **Changes**: 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}`. full_name: type: string description: | Full name of the user or bot, used for all display purposes. is_admin: type: boolean description: | A boolean specifying whether the user is an organization administrator. 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). role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: | [Organization-level role](/help/roles-and-permissions)) of the user. Poosible values are: * Organization owner => 100 * Organization administrator => 200 * Organization moderator => 300 * Member => 400 * Guest => 600 **Changes**: New in Zulip 4.0 (feature level 59). 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. user_id: type: integer description: | The unique ID of the user. bot_owner_id: type: integer nullable: true description: | If the user is a bot (i.e. `is_bot` is `True`), `bot_owner` 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. is_active: type: boolean description: | A boolean specifying whether the user account has been deactivated. is_guest: type: boolean description: | A boolean specifying whether the user is a guest user. timezone: type: string description: | The time zone of the user. date_joined: type: string description: | The time the user account was created. delivery_email: type: string description: | The user's real email address. This field is present only if [email address visibility](/help/restrict-visibility-of-email-addresses) is limited and you are an administrator with access to real email addresses under the configured policy. profile_data: $ref: "#/components/schemas/profile_data" profile_data: type: object description: | 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 user filled in the custom profile field with id `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: {} JsonSuccessBase: allOf: - $ref: "#/components/schemas/JsonResponseBase" - required: - result - msg properties: result: enum: - success msg: type: string example: {"msg": "", "result": "success"} JsonError: allOf: - $ref: "#/components/schemas/JsonErrorBase" - additionalProperties: false properties: result: {} msg: {} JsonErrorBase: allOf: - $ref: "#/components/schemas/JsonResponseBase" - required: - result - msg properties: result: enum: - error msg: type: string ApiKeyResponse: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - required: - api_key - email additionalProperties: false properties: result: {} msg: {} 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 example: { "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv", "email": "iago@zulip.com", "msg": "", "result": "success", } CodedError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} CodedErrorBase: allOf: - $ref: "#/components/schemas/JsonErrorBase" - properties: result: {} msg: {} 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: 1518820930:1", "queue_id": "1518820930:1", "result": "error", } InvalidMessageError: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} raw_content: type: string description: | The raw content of the message. example: { "msg": "Invalid message(s)", "code": "BAD_REQUEST", "result": "error", } NonExistingStreamError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} stream: type: string description: | The name of the stream that could not be found. example: { "code": "STREAM_DOES_NOT_EXIST", "msg": "Stream 'nonexistent_stream' does not exist", "result": "error", "stream": "nonexistent_stream", } AddSubscriptionsResponse: allOf: - $ref: "#/components/schemas/JsonSuccessBase" - additionalProperties: false properties: result: {} msg: {} subscribed: type: object description: | A dictionary where the key is the email address of the user/bot and the value is a list of the names of the streams that were subscribed to as a result of the query. additionalProperties: description: | `{email_address}`: List of the names of the streams that were subscribed to as a result of the query. type: array items: type: string already_subscribed: type: object description: | A dictionary where the key is the email address of the user/bot and the value is a list of the names of the streams that the user/bot is already subscribed to. additionalProperties: description: | `{email_address}`: List of the names of the streams that the user is already subscribed to. type: array items: type: string unauthorized: type: array items: type: string description: | A list of names of streams that the requesting user/bot was not authorized to subscribe to. Only present if `authorization_errors_fatal=false`. InvalidApiKeyError: allOf: - $ref: "#/components/schemas/JsonError" - example: {"msg": "Invalid API key", "result": "error"} MissingArgumentError: allOf: - $ref: "#/components/schemas/CodedErrorBase" - additionalProperties: false properties: result: {} msg: {} code: {} var_name: type: string description: | It contains the information about the missing parameter. example: { "code": "REQUEST_VARIABLE_MISSING", "msg": "Missing 'content' argument", "result": "error", "var_name": "content", } UserNotAuthorizedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "BAD_REQUEST", "msg": "User not authorized for this query", "result": "error", } UserDeactivatedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "USER_DEACTIVATED", "msg": "Account is deactivated", "result": "error", } RealmDeactivatedError: allOf: - $ref: "#/components/schemas/CodedError" - example: { "code": "REALM_DEACTIVATED", "msg": "This organization is deactivated", "result": "error", } ################### # Shared responses ################### responses: SimpleSuccess: description: Success. content: application/json: schema: $ref: "#/components/schemas/JsonSuccess" #################### # Shared parameters #################### parameters: Event_types: name: event_types in: query description: | A JSON-encoded array indicating which types of events you're interested in. Values that you might find useful include: * **message** (messages) * **subscription** (changes in your subscriptions) * **realm_user** (changes to users in the organization and their properties, such as their name). If you do not specify this parameter, you will receive all events, and have to filter out the events not relevant to your client in your client code. For most applications, one is only interested in messages, so one specifies: `event_types=['message']` Event types not supported by the server are ignored, in order to simplify the implementation of client apps that support multiple server versions. content: application/json: schema: type: array items: type: string example: ["message"] required: false Narrow: name: narrow in: query description: | A JSON-encoded array of arrays of length 2 indicating the narrow for which you'd like to receive events for. For instance, to receive events for the stream `Denmark`, you would specify `narrow=[['stream', 'Denmark']]`. Another example is `narrow=[['is', 'private']]` for private messages. Default is `[]`. content: application/json: schema: type: array items: type: array items: type: string default: [] example: [["stream", "Denmark"]] required: false AllPublicStreams: name: all_public_streams in: query description: | Whether you would like to request message events from all public streams. Useful for workflow bots that you'd like to see all new messages sent to public streams. (You can also subscribe the user to private streams). schema: type: boolean default: false example: true UserGroupId: name: user_group_id in: path description: | The ID of the target user group. schema: type: integer example: 1 required: true Topic: name: topic in: query description: | The topic of the message. Only required for stream messages (`type="stream"`), ignored otherwise. Maximum length of 60 characters. **Changes**: New in Zulip 2.0. Previous Zulip releases encoded this as `subject`, which is currently a deprecated alias. schema: type: string example: Castle QueueId: name: queue_id in: query description: | The ID of an event queue that was previously registered via `POST /api/v1/register` (see [Register a queue](/api/register-queue)). schema: type: string example: 1375801870:2942 required: true StreamIdInPath: name: stream_id in: path description: | The ID of the stream to access. schema: type: integer example: 1 required: true ClientGravatar: name: client_gravatar in: query description: | Whether the client supports computing gravatars URLs. If enabled, `avatar_url` will be included in the response only if there is a Zulip avatar, and will be `null` for users who are using gravatar as their avatar. This option significantly reduces the compressed size of user data, since gravatar URLs are long, random strings and thus do not compress well. The `client_gravatar` field is set to `true` if clients can compute their own gravatars. schema: type: boolean default: false example: true RequiredContent: name: content in: query description: | The content of the message. Maximum message size of 10000 bytes. schema: type: string example: Hello required: true OptionalContent: name: content in: query description: | The content of the message. Maximum message size of 10000 bytes. schema: type: string example: Hello MessageId: name: message_id in: path description: | The target message's ID. schema: type: integer example: 42 required: true UserId: name: user_id in: path description: | The target user's ID. schema: type: integer example: 12 required: true MutedUserId: name: muted_user_id in: path description: | The ID of the user to mute/un-mute. schema: type: integer example: 10 required: true StreamPostPolicy: name: stream_post_policy in: query description: | Policy for which users can post messages to the stream. * 1 => Any user can post. * 2 => Only administrators can post. * 3 => Only full members can post. * 4 => Only moderators can post. **Changes**: New in Zulip 3.0, replacing the previous `is_announcement_only` boolean. schema: type: integer default: 1 example: 2 required: false HistoryPublicToSubscribers: name: history_public_to_subscribers in: query description: | Whether the stream's message history should be available to newly subscribed members, or users can only access messages they actually received while subscribed to the stream. Corresponds to the [shared history](/help/stream-permissions) option in documentation. schema: type: boolean example: false required: false IncludeSubscribers: name: include_subscribers in: query description: | Whether each returned stream object should include a `subscribers` field containing a list of the user IDs of its subscribers. (This may be significantly slower in organizations with thousands of users subscribed to many streams.) **Changes**: New in Zulip 2.1.0. schema: type: boolean default: false example: true IncludeCustomProfileFields: name: include_custom_profile_fields in: query description: | Whether the client wants [custom profile field](/help/add-custom-profile-fields) data to be included in the response. **Changes**: New in Zulip 2.1.0. Previous versions do no offer these data via the API. schema: type: boolean default: false example: true Principals: name: principals in: query description: | A list of user ids (preferred) or Zulip display email addresses of the users to be subscribed to or unsubscribed from the streams specified in the `subscriptions` parameter. If not provided, then the requesting user/bot is subscribed. **Changes**: The integer format is new in Zulip 3.0 (feature level 9). content: application/json: schema: type: array items: oneOf: - type: string - type: integer example: ["ZOE@zulip.com"] ReactionType: name: reaction_type in: query description: | If an app 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`: Unicode emoji (`emoji_code` will be its Unicode codepoint). * `realm_emoji`: Custom emoji. (`emoji_code` will be its ID). * `zulip_extra_emoji`: Special emoji included with Zulip. Exists to namespace the `zulip` emoji. **Changes**: In Zulip 3.0 (feature level 2), this become optional for [custom emoji](/help/add-custom-emoji); previously, this endpoint assumed `unicode_emoji` if this parameter was not specified. schema: type: string example: "unicode_emoji" required: false EmojiCode: name: emoji_code in: query description: | A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. For most API clients, you won't need this, but it's important for Zulip apps to handle rare corner cases when adding/removing votes on an emoji reaction added previously by another user. If the existing reaction was added when the Zulip server was using a previous version of the emoji data mapping between Unicode codepoints and human-readable names, sending the `emoji_code` in the data for the original reaction allows the Zulip server to correctly interpret your upvote as an upvote rather than a reaction with a "diffenent" emoji. schema: type: string example: "1f419" required: false MessageRetentionDays: name: message_retention_days in: query description: | Number of days that messages sent to this stream will be stored before being automatically deleted by the [message retention policy](/help/message-retention-policy). Two special string format values are supported: * "realm_default" => Return to the organization-level setting. * "forever" => Retain messages forever. **Changes**: New in Zulip 3.0 (feature level 17). schema: oneOf: - type: string - type: integer example: "20" required: false LinkifierPattern: name: pattern in: query description: | The [Python regular expression](https://docs.python.org/3/howto/regex.html) that should trigger the linkifier. schema: type: string example: "#(?P