Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.
", "flags": [ "read" ], "id": 16, "display_recipient": [ { "short_name": "hamlet", "id": 4, "is_mirror_dummy": false, "email": "hamlet@zulip.com", "full_name": "King Hamlet" }, { "short_name": "iago", "id": 5, "is_mirror_dummy": false, "email": "iago@zulip.com", "full_name": "Iago" }, { "short_name": "prospero", "id": 8, "is_mirror_dummy": false, "email": "prospero@zulip.com", "full_name": "Prospero from The Tempest" } ], "content_type": "text/html", "is_me_message": false, "sender_short_name": "hamlet", "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, "sender_short_name": "hamlet", "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: description: Send a message. 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: The destination stream, or a CSV/JSON-encoded list containing the usernames (emails) of the recipients. schema: type: string example: aaron@zulip.com, iago@zulip.com required: true - name: topic in: query description: The topic of the message. Only required if `type` is `stream`, ignored otherwise. Maximum length of 60 characters. schema: type: string default: example: Castle - name: content in: query description: The content of the message. Maximum message size of 10000 bytes. schema: type: string example: Hello required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: id: type: integer description: The ID assigned to the message sent. - example: { "msg": "", "id": 42, "result": "success" } '400_non_existing_stream': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/NonExistingStreamError' '400_non_existing_user': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: { "code": "BAD_REQUEST", "msg": "Invalid email 'eeshan@zulip.com'", "result": "error" } /messages/{message_id}: get: description: Get the raw content of a message. parameters: - name: message_id in: path description: The target message's ID. schema: type: integer example: 42 required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: 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: description: Edit a message that has already been sent. parameters: - name: message_id in: path description: The ID of the message that you wish to edit/update. schema: type: integer example: 42 required: true - name: topic in: query description: The topic of the message. Only required for stream messages. Maximum length of 60 characters. schema: type: string default: example: Castle - 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." schema: type: string enum: - change_one - change_later - change_all default: change_one example: change_all - name: content in: query description: The content of the message. Maximum message size of 10000 bytes. schema: type: string example: Hello 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' - 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: description: Delete a message. parameters: - name: message_id in: path description: The ID of the message to delete. schema: type: integer example: 42 required: true responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess' '400_invalid_message': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/InvalidMessageError' '400_not_admin': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: { "code": "BAD_REQUEST", "msg": "You don't have permission to delete this message", "result": "error" } /messages/{message_id}/history: get: description: Get the different versions of a previously edited message. parameters: - name: message_id in: path description: The ID of the message you want to fetch the history of. schema: type: integer example: 42 required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: message_history: type: array items: type: object description: A chronologically sorted array of `snapshot` objects, each one with the values of the message after the edition. - 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: description: Add an emoji reaction to a message. parameters: - name: message_id in: path description: The ID of the message that you want to add an emoji reaction to. schema: type: integer example: 42 required: true - name: emoji_name in: query description: | Name of the emoji you want to add as as a reaction. 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: '**:slight smile:**' required: true - name: emoji_code in: query description: | An encoded version of the unicode codepoint. Used only in rare corner cases to consolidate identical reactions to the same emoji name. schema: type: string example: '**foo**' required: false - name: reaction_type in: query description: | If you are reacting with a [custom emoji](/help/add-custom-emoji), set `reaction_type` to `realm_emoji`. schema: type: string example: '**realm_emoji**' required: false responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: rendered: type: string description: The rendered HTML. - example: { "msg": "", "rendered": "foo
", "result": "success" } delete: description: Delete an emoji reaction from a message. parameters: - name: message_id in: path description: The ID of the message from which you want to delete the emoji reaction. schema: type: integer example: 42 required: true - name: emoji_name in: query description: | Name of the emoji you want to delete from a reaction. 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: '**:slight smile:**' required: true - name: emoji_code in: query description: | An encoded version of the unicode codepoint for the emoji. Should be passed when adding a vote to an existing emoji reaction, or order to handle unlikely corner cases where the emoji name to codepoint mapping has changed since the first reaction was added. schema: type: string example: '**foo**' required: false - name: reaction_type in: query description: | If you are reacting with a [custom emoji](/help/add-custom-emoji), set `reaction_type` to `realm_emoji`. schema: type: string example: '**realm_emoji**' required: false responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: rendered: type: string description: The rendered HTML. - example: { "msg": "", "rendered": "foo
", "result": "success" } /user_uploads: post: description: Upload a single file and get the corresponding URI. requestBody: content: multipart/form-data: schema: properties: filename: type: string format: binary example: /path/to/file responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: uri: type: string description: The URI of the uploaded file. - example: { "msg": "", "result": "success", "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt" } /users: get: description: Retrieve all users in a realm. parameters: - name: client_gravatar in: query description: The `client_gravatar` field is set to `true` if clients can compute their own gravatars. schema: type: boolean default: false example: true - name: include_custom_profile_fields in: query description: Set to `true` if the client wants custom profile field data to be included in the response. schema: type: boolean default: false example: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: members: type: array description: A list of `member` objects, each containing details of a user in the realm (like their email, name, avatar, user type...). - example: { "msg": "", "result": "success", "members": [ { "is_active": true, "email": "AARON@zulip.com", "is_admin": false, "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, "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, "user_id": 23, "bot_type": 1, "timezone": "", "is_bot": true } ] } post: description: Create a new user in a realm. 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 - name: short_name in: query description: The short name of the new user. Not user-visible. schema: type: string example: newuser required: true 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: { "msg": "Email 'newbie@zulip.com' already in use", "result": "error" } /users/{user_id}: get: description: Retrieve a user in a realm. parameters: - name: user_id in: path description: The user id of the user. schema: type: integer example: 11 required: true - name: client_gravatar in: query description: The client should pass true if it can compute its own gravatar hashes. schema: type: boolean default: false example: true - name: include_custom_profile_fields in: query description: The client should pass true if it wants to include custom profile field data. schema: type: boolean default: false example: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: members: type: array description: A list `member` containing a single object with details of a user in the realm (like their email, name, avatar, user type...). - example: { "msg": "", "result": "success", "members": [ { "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, "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", "is_active": true, "email": "hamlet@zulip.com" } ] } patch: description: Update the user. parameters: - name: user_id in: path description: The user id of the user. schema: type: integer example: 12 required: true - name: full_name in: query description: The user's full name. schema: type: string format: json example: NewName required: false - name: is_admin in: query description: Whether the target user is an administrator. schema: type: boolean example: false required: false - name: is_guest in: query description: Whether the target user is a guest. schema: type: boolean example: true required: false - name: profile_data in: query description: A dictionary containing the to be updated custom profile field data for the user. schema: type: array items: type: object example: [ { "id":1, "value":"short text data" }, { "id":2, "value":"long text data" }, { "id":3, "value":"short text data" }, { "id":4, "value":"vim" }, { "id":5, "value":"1909-3-5" }, { "id":6, "value":"https:\/\/zulipchat.com" }, { "id":7, "value":[ 12 ] }, { "id":8, "value":"cordelia" } ] required: false 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/CodedError' - example: { "result": "error", "msg": "Guests cannot be organization administrators", "code": "BAD_REQUEST" } delete: description: Delete the user with the passed 'user_id' from the realm. parameters: - name: user_id in: path description: The user id of the user. schema: type: integer example: 11 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: { "msg": "Cannot deactivate the only organization administrator", "result": "error" } /users/{email}/presence: get: description: Get the presence status for a specific user. parameters: - name: email in: path description: The email address of the user whose presence you want to fetch. schema: type: string example: iago@zulip.com required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: presence: type: object description: An object containing the presence details for every client the user has logged into. - example: { "presence": { "website": { "timestamp": 1532697622, "status": "active", }, "ZulipMobile": { "timestamp": 1522687421, "status": "active", }, "aggregated": { "timestamp": 1532697622, "status": "active", } }, "result": "success", "msg": "" } /users/me: get: description: Get the requesting user's profile data from the backend. responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: avatar_url: type: string description: "URL for the user's avatar" example: "x" client_id: type: string description: NA example: "74c768b081076fdb3c4326256c17467e" 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_bot: type: boolean description: A boolean indicating if the requesting user is a bot. example: false max_message_id: type: integer description: NA. example: 30 pointer: type: integer description: NA example: -1 short_name: type: string description: Short name of the requesting user. example: "iago" user_id: type: integer description: The user's ID. example: 1 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. - example: { "avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1", "client_id": "74c768b081076fdb3c4326256c17467e", "email": "iago@zulip.com", "full_name": "Iago", "is_admin": true, "is_bot": false, "max_message_id": 30, "msg": "", "pointer": -1, "result": "success", "short_name": "iago", "user_id": 5, "profile_data": { "5": { "value": "2000-1-1" }, "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: description: Delete the requesting user from the realm. responses: '200': description: Bad Request 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 administrator", "result": "error" } /users/me/{stream_id}/topics: get: description: Get all the topics in a specific stream. parameters: - name: stream_id in: path description: The unique ID of the stream. schema: type: integer example: 42 required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: topics: type: array items: type: object properties: max_id: description: The ID of the last message sent to the topic. type: number 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: description: Get information on every stream the user is subscribed to. parameters: - name: include_subscribers in: query description: Set to `true` if you would like each stream's info to include a list of current subscribers to that stream. (This may be significantly slower in organizations with thousands of users.) schema: type: boolean default: false example: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: subscriptions: type: array items: type: object - example: { "msg": "", "result": "success", "subscriptions": [ { "audible_notifications": true, "color": "#e79ab5", "description": "A Scandinavian country", "desktop_notifications": true, "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", "in_home_view": true, "invite_only": false, "name": "Denmark", "pin_to_top": false, "push_notifications": false, "stream_id": 1, "subscribers": [ "ZOE@zulip.com", "hamlet@zulip.com", "iago@zulip.com", "othello@zulip.com", "prospero@zulip.com" ] }, { "audible_notifications": true, "color": "#e79ab5", "description": "Located in the United Kingdom", "desktop_notifications": true, "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", "in_home_view": true, "invite_only": false, "name": "Scotland", "pin_to_top": false, "push_notifications": false, "stream_id": 3, "subscribers": [ "ZOE@zulip.com", "iago@zulip.com", "othello@zulip.com", "prospero@zulip.com" ] } ] } post: description: Subscribe one or more users to one or more streams. parameters: - name: subscriptions in: query description: "A list of dictionaries containing the 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. **Note**: This argument is called `streams` and not `subscriptions` in our Python API." schema: type: array items: type: object example: [{"name": "Verona", "description": "Italian City"}] required: true - name: invite_only in: query description: A boolean specifying whether the streams specified in `subscriptions` are invite-only or not. schema: type: boolean default: false example: true - name: principals in: query description: A list of email addresses of the users that will be subscribed to the streams specified in the `subscriptions` argument. If not provided, then the requesting user/bot is subscribed. schema: type: array items: type: string default: [] example: ['ZOE@zulip.com'] - 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 returned JSON payload indicates that there was an authorization error, but the response is still considered a successful one. schema: type: boolean default: true example: false - name: history_public_to_subscribers in: query description: A boolean indicating if the history should be available to newly subscribed members. schema: type: boolean default: None example: false - name: stream_post_policy in: query description: Indicates which users can post messages to the stream. schema: type: integer default: 1 example: 1 - name: announce in: query description: If `announce` is `True` and one of the streams specified in `subscriptions` has to be created (i.e. doesn't exist to begin with), an announcement will be made notifying that a new stream was created. schema: type: boolean example: true responses: '200_without_principals': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/AddSubscriptionsResponse' - example: { "already_subscribed": {}, "msg": "", "result": "success", "subscribed": { "iago@zulip.com": [ "new stream" ] } } '200_already_subscribed': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/AddSubscriptionsResponse' - example: { "already_subscribed": { "newbie@zulip.com": [ "new stream" ] }, "msg": "", "result": "success", "subscribed": {} } '400_unauthorized_errors_fatal_true': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/AddSubscriptionsResponse' - example: { "msg": "Unable to access stream (private_stream).", "result": "error" } '400_unauthorized_errors_fatal_false': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/AddSubscriptionsResponse' - example: { "already_subscribed": {}, "msg": "", "result": "success", "subscribed": {}, "unauthorized": [ "private_stream" ] } patch: description: Update which streams you are are subscribed to. parameters: - name: delete in: query description: A list of stream names to unsubscribe from. 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. schema: type: array items: type: object 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/JsonSuccess' - properties: 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. 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. 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: description: Unsubscribe yourself or other users from one or more streams. parameters: - name: subscriptions in: query description: A list of stream names to unsubscribe from. This argument is called `streams` in our Python API. schema: type: array items: type: string example: ['Verona', 'Denmark'] required: true - name: principals in: query description: A list of email addresses of the users that will be unsubscribed from the streams specified in the `subscriptions` argument. If not provided, then the requesting user/bot is unsubscribed. schema: type: array items: type: string default: example: ['ZOE@zulip.com'] responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: 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: description: Toggle muting for a specific topic the user is subscribed to. parameters: - name: stream in: query description: The name of the stream in which to mute the topic. schema: type: string example: Verona required: false - name: stream_id in: query description: The id of the stream in which to mute the topic. schema: type: integer example: 3 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_topic_already_muted': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonError' - example: { "msg": "Topic already muted", "result": "error" } '400_topic_not_muted': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonError' - example: { "msg": "Topic is not muted", "result": "error" } /realm/emoji/{emoji_name}: post: description: Upload a single emoji file. 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: properties: filename: type: string format: binary example: /path/to/img.png responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' /realm/emoji: get: description: Get all the custom emoji in the user's realm. responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: emoji: type: object description: An object that contains `emoji` objects, each identified with their emoji ID as the key. - 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, "email": "iago@zulip.com", "full_name": "Iago" } } } } /users/me/subscriptions/properties: post: description: Make bulk modifications of the subscription properties on one or more streams the user is subscribed to. 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`. 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/JsonSuccess' - properties: subscription_data: type: array items: type: object description: The same `subscription_data` object sent by the client for the request. - example: { "subscription_data": [ { "property": "pin_to_top", "value": true, "stream_id": 1 }, { "property": "color", "value": 'f00', "stream_id": 3 } ], "result": "success", "msg": "" } /realm/filters: get: description: Fetch all the filters set up for the user's organization. responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: filters: type: array items: type: array items: oneOf: - type: string - type: integer description: An array of tuples, each representing one of the linkifiers set up in the organization. Each of these tuples contain the pattern, the formatted URL and the filter's ID, in that order. See the [Create linkifiers](/api/add-linkifiers) article for details on what each field means. - example: { "msg": "", "filters": [ [ "#(?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: description: Modify the user's preferences for 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. schema: type: string format: json 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_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 missed messages email notifications. 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 schema: type: integer enum: - 1 - 2 - 3 example: 1 - name: realm_name_in_notifications in: query description: Include organization name in subject of missed message emails. schema: type: boolean example: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: 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_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" } /streams: get: description: Get all streams that the user has access to. parameters: - name: include_public in: query description: Include all public streams. schema: type: boolean default: true example: false - 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/JsonSuccess' - properties: streams: type: array items: type: object description: A list of `stream` objects, which contain a `description`, a `name`, their `stream_id` and whether they are `invite_only` or not. - 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: description: Delete the stream with the given ID. parameters: - name: stream_id in: path description: The ID of the stream to be deleted. schema: type: integer example: 42 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: { "code": "BAD_REQUEST", "msg": "Invalid stream id", "result": "error" } patch: description: Update the stream with the given ID. parameters: - name: stream_id in: path description: The ID of the stream to be updated. schema: type: integer example: 42 required: true - name: description in: query description: The new description for the stream. schema: type: string format: json example: "This stream is related to football dicsussions." required: false - name: new_name in: query description: The new name for the stream. schema: type: string format: json example: "Italy" required: false - name: is_private in: query description: The new state of the stream. schema: type: boolean example: true required: false - name: is_announcement_only in: query description: The new state for the announcements. schema: type: boolean example: true required: false - name: stream_post_policy in: query description: Indicates which users can post messages to the stream. schema: type: integer example: 2 required: false - name: history_public_to_subscribers in: query description: The new state for the history_public_to_subscribers. schema: type: boolean example: true required: false 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: description: Send an event indicating that the user has started or stopped typing on their client. parameters: - 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: The recipients of the message being typed, in the same format used by the send_message API. Typing notifications are only supported for private messages, so this should be a JSON-encoded list of email addresses of the message's recipients. schema: type: array items: type: string example: ["iago@zulip.com", "polonius@zulip.com"] required: true responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess' /user_groups/create: post: description: Create a user group. 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. 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/{group_id}: patch: description: Update the user group. parameters: - name: group_id in: path description: The ID of the group. schema: type: integer example: 42 required: true - 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': 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" } delete: description: Delete the user group. parameters: - name: group_id in: path description: The ID of the group. schema: type: integer example: 42 required: true 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: description: Get all user groups of the realm. responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: user_groups: type: array items: type: object 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] } ] } 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: JsonResponse: type: object properties: result: type: string JsonSuccess: allOf: - $ref: '#/components/schemas/JsonResponse' - required: - result - msg - properties: result: enum: - success msg: type: string - example: { "msg": "", "result": "success" } JsonError: allOf: - $ref: '#/components/schemas/JsonResponse' - required: - result - msg - properties: result: enum: - error msg: type: string ApiKeyResponse: allOf: - $ref: '#/components/schemas/JsonSuccess' - properties: 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/JsonError' - properties: code: type: string description: A string that identifies the error. BadEventQueueIdError: allOf: - $ref: '#/components/schemas/CodedError' - properties: 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/JsonSuccess' - properties: 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/CodedError' - properties: 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/JsonSuccess' - properties: 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. 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. unauthorized: type: array items: type: string description: A list of names of streams that the requesting user/bot was not authorized to subscribe to. ################### # Shared responses ################### responses: SimpleSuccess: description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess'