I am:
+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 delivery_email: null is_imported_stub: false - bot_owner_id: 11 is_guest: false date_joined: '2019-10-20T12:52:17.862053+00:00' full_name: Iago's Bot email: iago-bot@zulipdev.com delivery_email: iago-bot@zulipdev.com is_active: true avatar_url: https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1 is_admin: false is_owner: false role: 400 user_id: 23 bot_type: 1 timezone: '' is_bot: true is_imported_stub: false post: operationId: create-user summary: Create a user tags: - users description: "Create a new user account via the API.\n\n!!! warn \"\"\n\n **Note**: On Zulip Cloud, this feature is available only for\n organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)\n or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators\n can request the required `can_create_users` permission for a bot or\n user by contacting [Zulip Cloud support][support] with an\n explanation for why it is needed. Self-hosted installations can\n toggle `can_create_users` on an account using the `manage.py\n change_user_role` [management command][management-commands].\n\n**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was\navailable to all organization administrators.\n\n[support]: /help/contact-support\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n" x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: email: description: 'The email address of the new user. ' type: string example: username@example.com password: description: 'The password of the new user. ' type: string example: abcd1234 full_name: description: 'The full name of the new user. ' type: string example: New User required: - email - password - full_name responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user_id: type: integer description: 'The ID assigned to the newly created user. **Changes**: New in Zulip 4.0 (feature level 30). ' example: msg: '' result: success user_id: 25 '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Email is already in use. result: error description: 'A typical JSON response for when another user with the same email address already exists in the realm: ' /users/{user_id}/reactivate: post: operationId: reactivate-user summary: Reactivate a user tags: - users x-requires-administrator: true description: '[Reactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. ' parameters: - $ref: '#/components/parameters/UserId' responses: '200': $ref: '#/components/responses/SimpleSuccess' /users/{user_id}/status: post: operationId: update-status-for-user summary: Update user status tags: - users parameters: - $ref: '#/components/parameters/UserId' description: 'Administrator endpoint for changing the [status](/help/status-and-availability) of another user. **Changes**: Prior to Zulip 12.0 (feature level 473), only bots could not access this API endpoint, regardless of the role of the bot. New in Zulip 11.0 (feature level 407). ' x-requires-administrator: true requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: status_text: type: string description: 'The text content of the status message. Sending the empty string will clear the user''s status. **Note**: The limit on the size of the message is 60 Unicode code points. ' example: on vacation emoji_name: type: string description: 'The name for the emoji to associate with this status. **Changes**: New in Zulip 5.0 (feature level 86). ' example: car emoji_code: type: string description: 'A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. **Changes**: New in Zulip 5.0 (feature level 86). ' example: 1f697 reaction_type: type: string description: "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" example: unicode_emoji responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Insufficient permission code: BAD_REQUEST description: 'An example JSON error response user making request does not have permission to update other user''s status.: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Client did not pass any new values. code: BAD_REQUEST description: 'An example JSON error response when no changes were requested: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: 'status_text is too long (limit: 60 characters)' code: BAD_REQUEST description: 'An example JSON error response when the `status_text` message exceeds the limit of 60 characters: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Client must pass emoji_name if they pass either emoji_code or reaction_type. code: BAD_REQUEST description: 'An example JSON error response when `emoji_name` is not specified but `emoji_code` or `reaction_type` is specified: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Emoji 'invalid' does not exist code: BAD_REQUEST description: 'An example JSON error response when the emoji name does not exist: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Invalid emoji name. code: BAD_REQUEST description: 'An example JSON error response when the emoji name is invalid: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Invalid custom emoji. code: BAD_REQUEST description: 'An example JSON error response when the custom emoji is invalid: ' get: operationId: get-user-status summary: Get a user's status tags: - users description: 'Get the [status](/help/status-and-availability) currently set by a user in the organization. **Changes**: New in Zulip 9.0 (feature level 262). Previously, user statuses could only be fetched via the [`POST /register`](/api/register-queue) endpoint. ' parameters: - $ref: '#/components/parameters/UserId' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} status: allOf: - description: 'The status set by the user. Note that, if the user doesn''t have a status currently set, then the returned dictionary will be empty as none of the keys listed below will be present. ' - $ref: '#/components/schemas/UserStatus' example: result: success msg: '' status: status_text: on vacation emoji_name: car emoji_code: 1f697 reaction_type: unicode_emoji '400': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: No such user code: BAD_REQUEST description: 'An example JSON error response when the user does not exist: ' /users/{user_id_or_email}/presence: get: operationId: get-user-presence summary: Get a user's presence tags: - users description: 'Get the presence status for a specific user. This endpoint is most useful for embedding data about a user''s presence status in other sites (e.g. an employee directory). Full Zulip clients like mobile/desktop apps will want to use the [main presence endpoint](/api/get-presence), which returns data for all active users in the organization, instead. ' parameters: - name: user_id_or_email in: path description: 'The ID or Zulip API email address of the user whose presence you want to fetch. **Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported identifying the user by Zulip API email. ' schema: type: string example: iago@zulip.com required: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} server_timestamp: type: number description: 'The time when the server fetched the `presence` data included in the response. Matches the similar field in other presence responses. **Changes**: New in Zulip 12.0 (feature level 497). ' presence: type: object additionalProperties: false description: 'An object containing the presence details for the user. The object contains both the modern format fields (`active_timestamp` and `idle_timestamp`) and the legacy format fields (`website` and `aggregated` dictionaries, which contain a timestamp and a status string). New integrations should use the modern fields; the legacy fields are retained for backwards compatibility. **Changes**: In Zulip 12.0 (feature level 497), the `website` and `aggregated` legacy dictionaries were restored alongside the modern fields, for backwards compatibility with integrations written against earlier versions of the API. In Zulip 12.0 (feature level 487), the `active_timestamp` and `idle_timestamp` fields were added to this object, and the `website` and `aggregated` dictionaries were temporarily removed. ' required: - website - aggregated properties: active_timestamp: type: integer description: 'The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present. ' idle_timestamp: type: integer description: 'The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients. ' website: type: object additionalProperties: false description: 'Presence details for the user in the legacy format. Starting with Zulip 7.0 (feature level 178), the `website` and `aggregated` dictionaries always contain identical data, since the server no longer stores which client submitted presence updates. ' properties: status: type: string enum: - idle - active description: 'The status of the user. Will be either `"idle"` or `"active"`. ' timestamp: type: integer description: 'The UNIX timestamp of when the user''s presence data was last updated. ' aggregated: type: object additionalProperties: false description: 'Presence details for the user in the legacy format. Unlike `website`, the `status` will be `"offline"` if the most recent presence update is older than the server''s offline threshold. ' properties: status: type: string enum: - idle - active - offline description: 'The status of the user. Will be either `"idle"`, `"active"`, or `"offline"`. ' timestamp: type: integer description: 'The UNIX timestamp of when the user''s presence data was last updated. ' example: msg: '' server_timestamp: 1656958540.123 presence: active_timestamp: 1656958520 idle_timestamp: 1656958530 website: status: active timestamp: 1656958520 aggregated: status: active timestamp: 1656958520 result: success /users/me: get: operationId: get-own-user summary: Get own user tags: - users description: 'Get basic data about the user/bot that requests this endpoint. **Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was replaced by the `can_manage_billing_group` realm setting. ' responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} avatar_url: type: string description: 'URL for the requesting user''s avatar. **Changes**: New in Zulip 2.1.0. ' example: x avatar_version: type: integer description: 'Version for the requesting user''s avatar. Used for cache-busting requests for the user''s avatar. Clients generally shouldn''t need to use this; most avatar URLs sent by Zulip will already end with `?v={avatar_version}`. **Changes**: New in Zulip 3.0 (feature level 10). ' example: 1 email: type: string description: 'Zulip API email of the requesting user. ' example: iago@zulip.com full_name: type: string description: 'Full name of the requesting user. ' example: Iago is_admin: type: boolean description: 'A boolean indicating if the requesting user is an admin. ' example: true is_owner: type: boolean description: 'A boolean indicating if the requesting user is an organization owner. **Changes**: New in Zulip 3.0 (feature level 8). ' example: false role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: '[Organization-level role](/api/roles-and-permissions) of the requesting user. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest **Changes**: New in Zulip 4.0 (feature level 59). ' is_guest: type: boolean description: 'A boolean indicating if the requesting user is a guest. **Changes**: New in Zulip 3.0 (feature level 10). ' example: false is_bot: type: boolean description: 'A boolean indicating if the requesting user is a bot. ' example: false is_active: type: boolean description: 'A boolean specifying whether the requesting user account has been deactivated. **Changes**: New in Zulip 3.0 (feature level 10). ' example: true timezone: type: string description: 'The IANA identifier of the requesting user''s [profile time zone](/help/change-your-timezone), which is used primarily to display the user''s local time to other users. **Changes**: New in Zulip 3.0 (feature level 10). ' example: '' date_joined: type: string description: 'The time when the user joined. For users imported from other applications and users created via the API, this is set to the account creation time until the user logs in for the first time, after which it is updated to that login time. For imported users, clients can use the `is_imported_stub` flag to determine how to display this field: when `is_imported_stub` is `true`, the user has not yet logged in and this value is the account creation time during import; when `is_imported_stub` is `false`, this value reflects when the user first logged in. **Changes**: Starting with Zulip 12.0 (feature level 475), this field is updated when an imported stub user or a user created via the API logs in for the first time. New in Zulip 3.0 (feature level 10). ' example: '2019-10-20T07:50:53.728864+00:00' max_message_id: type: integer deprecated: true description: 'The integer ID of the last message received by the requesting user''s account. **Deprecated**. We plan to remove this in favor of recommending using `GET /messages` with `"anchor": "newest"`. ' example: 30 user_id: type: integer description: 'The user''s ID. ' example: 1 delivery_email: type: string description: 'The requesting user''s real email address. **Changes**: Prior to Zulip 7.0 (feature level 163), this field was present only when `email_address_visibility` was restricted and the requesting user had permission to access realm users'' emails. As of this feature level, this field is always present. ' is_imported_stub: type: boolean description: 'Indicates whether this user object is a stub account imported from another chat system. Stub accounts are used to represent the senders for imported messages. Stub accounts can be converted to regular Zulip accounts when the user starts using Zulip, preserving that imported user''s message history. **Changes**: New in Zulip 12.0 (feature level 433). ' example: false profile_data: $ref: '#/components/schemas/ProfileData' example: avatar_url: https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1 avatar_version: 1 email: iago@zulip.com delivery_email: iago@zulip.com full_name: Iago is_admin: true is_owner: false role: 200 is_guest: false is_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 is_imported_stub: false profile_data: '5': value: '2000-01-01' '4': value: emacs '7': value: '[10]' '1': value: +1-234-567-8901 rendered_value:+1-234-567-8901
'2': rendered_value:Betrayer of Othello.
value: Betrayer of Othello. '8': value: zulip '3': value: Apples rendered_value:Apples
'6': value: https://zulip.readthedocs.io/en/latest/ delete: operationId: deactivate-own-user summary: Deactivate own user tags: - users description: 'Deactivates the current user''s account. See also the administrative endpoint for [deactivating another user](/api/deactivate-user). This endpoint is primarily useful to Zulip clients providing a user settings UI. ' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false properties: result: {} msg: {} code: {} entity: type: string description: 'An internationalized string that notes if the current user is the only organization owner or the only user in the organization. ' is_last_owner: type: boolean description: 'Whether the current user is the only organization owner (meaning there are other active users in the organization) or the only active user in the organization. ' required: - entity - is_last_owner example: code: CANNOT_DEACTIVATE_LAST_USER msg: Cannot deactivate the only organization owner result: error entity: organization owner is_last_owner: true description: 'If the current user is the only organization owner or only user in the organization, their account cannot be deactivated and an error response will be returned. The `is_last_owner` field in the error response indicates whether the user is the only owner (`true`) or the only user (`false`). The `entity` field in the error response is a internationalized string that notes if the current user is the only organization owner or the only user. An example JSON error response when the current user is the only organization owner in the organization: ' /users/me/api_key/regenerate: post: operationId: regenerate-api-key summary: Regenerate your API key tags: - users description: "!!! warn \"\"\n\n **Note**: Users should treat their Zulip API key as\n [carefully as they would their password](/help/protect-your-account).\n\nGenerate a new API key for the user making the request.\n\nChanging a user's API key will immediately log them out of Zulip\non devices registered for [mobile push notifications][mobile-push].\n\n**Changes**: Before Zulip 12.0 (feature level 492),\nregenerating a user's API key didn't remove all of the user's\n[E2EE push device registrations](/api/register-push-device),\nso E2EE push notifications could still be sent.\n\n[mobile-push]: https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html\n" responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} api_key: type: string description: The new API key for the user. required: - api_key example: result: success msg: '' api_key: a1b2c3d4e5f6g7h8i9j0 /users/me/alert_words: get: operationId: get-alert-words summary: Get all alert words tags: - users description: 'Get all of the user''s configured [alert words][alert-words]. [alert-words]: /help/dm-mention-alert-notifications#alert-words ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: 'An array of strings, where each string is an alert word (or phrase) configured by the user. ' items: type: string example: result: success msg: '' alert_words: - natural - illustrious post: operationId: add-alert-words summary: Add alert words tags: - users description: 'Add words (or phrases) to the user''s set of configured [alert words][alert-words]. [alert-words]: /help/dm-mention-alert-notifications#alert-words ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: alert_words: description: 'An array of strings to be added to the user''s set of configured alert words. Strings already present in the user''s set of alert words already are ignored. Alert words are case insensitive. ' type: array items: type: string example: - foo - bar required: - alert_words encoding: alert_words: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: 'An array of strings, where each string is an alert word (or phrase) configured by the user. ' items: type: string example: result: success msg: '' alert_words: - foo - bar - natural - illustrious '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: 'alert_words[0] is too long (limit: 100 characters)' result: error description: 'An example JSON response for when a supplied alert word (or phrase) exceeds the character limit: ' delete: operationId: remove-alert-words summary: Remove alert words tags: - users description: 'Remove words (or phrases) from the user''s set of configured [alert words][alert-words]. Alert words are case insensitive. [alert-words]: /help/dm-mention-alert-notifications#alert-words ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: alert_words: description: 'An array of strings to be removed from the user''s set of configured alert words. Strings that are not in the user''s set of alert words are ignored. ' type: array items: type: string example: - foo required: - alert_words encoding: alert_words: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} alert_words: type: array description: 'An array of strings, where each string is an alert word (or phrase) configured by the user. ' items: type: string example: result: success msg: '' alert_words: - bar - natural - illustrious /users/me/presence: post: operationId: update-presence summary: Update your presence tags: - users description: "Update the current user's [presence][availability] and fetch presence data\nof other users in the organization.\n\nThis endpoint is meant to be used by clients for both:\n\n- Reporting the current user's presence status (`\"active\"` or `\"idle\"`)\n to the server.\n\n- Obtaining the presence data of all other users in the organization via\n regular polling.\n\nAccurate user presence is one of the most expensive parts of any\nchat application (in terms of bandwidth and other resources). Therefore,\nit is important that clients implementing Zulip's user presence system\nuse the modern [`last_update_id`](#parameter-last_update_id) protocol to\nminimize fetching duplicate user presence data.\n\nClient apps implementing presence are recommended to also consume [`presence`\nevents](/api/get-events#presence)), in order to learn about newly online users\nimmediately.\n\nThe Zulip server is responsible for implementing [invisible mode][invisible],\nwhich disables sharing a user's presence data. Nonetheless, clients\nshould check the `presence_enabled` field in user objects in order to\ndisplay the current user as online or offline based on whether they are\nsharing their presence information.\n\n**Changes**: As of Zulip 8.0 (feature level 228), if the\n`CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is\n`true`, then user presence data in the response is [limited to users\nthe current user can see/access][limit-visibility].\n\n[limit-visibility]: /help/guest-users#configure-whether-guests-can-see-all-other-users\n[invisible]: /help/status-and-availability#invisible-mode\n[availability]: /help/status-and-availability#availability\n" requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: last_update_id: type: integer description: 'The identifier that specifies what presence data the client already has received, which allows the server to only return more recent user presence data. This should be set to `-1` during initialization of the client in order to fetch all user presence data, unless the client is obtaining initial user presence metadata from the [`POST /register`](/api/register-queue) endpoint. In subsequent queries to this endpoint, this value should be set to the most recent value of `presence_last_update_id` returned by the server in this endpoint''s response, which implements incremental fetching of user presence data. When this parameter is passed, the user presence data in the response will always be in the modern format. **Changes**: New in Zulip 9.0 (feature level 263). Previously, the server sent user presence data for all users who had been active in the last two weeks unconditionally. ' example: 5 history_limit_days: type: integer description: 'Limits how far back in time to fetch user presence data. If not specified, defaults to 14 days. A value of N means that the oldest presence data fetched will be from at most N days ago. Note that this is only useful during the initial user presence data fetch, as subsequent fetches should use the `last_update_id` parameter, which will act as the limit on how much presence data is returned. `history_limit_days` is ignored if `last_update_id` is passed with a value greater than `0`, indicating that the client already has some presence data. **Changes**: New in Zulip 10.0 (feature level 288). ' example: 365 new_user_input: type: boolean description: 'Whether the user has interacted with the client (e.g. moved the mouse, used the keyboard, etc.) since the previous presence request from this client. The server uses data from this parameter to implement certain [usage statistics](/help/analytics). User interface clients that might run in the background, without the user ever interacting with them, should be careful to only pass `true` if the user has actually interacted with the client in order to avoid corrupting usage statistics graphs. ' example: false default: false ping_only: type: boolean description: 'Whether the client is sending a ping-only request, meaning it only wants to update the user''s presence `status` on the server. Otherwise, also requests the server return user presence data for all users in the organization, which is further specified by the [`last_update_id`](#parameter-last_update_id) parameter. ' example: false default: false slim_presence: type: boolean description: 'Legacy parameter for configuring the format (modern or legacy) in which the server will return user presence data for the organization. Modern clients should use [`last_update_id`](#parameter-last_update_id), which guarantees that user presence data will be returned in the modern format, and should not pass this parameter as `true` unless interacting with an older server. Legacy clients that do not yet support `last_update_id` may use the value of `true` to request the modern format for user presence data. **Note**: The legacy format for user presence data will be removed entirely in a future release. **Changes**: **Deprecated** in Zulip 9.0 (feature level 263). Using the modern `last_update_id` parameter is the recommended way to request the modern format for user presence data. New in Zulip 3.0 (no feature level as it was an unstable API at that point). ' example: false default: false deprecated: true status: type: string enum: - idle - active description: 'The status of the user on this client. Clients should report the user as `"active"` on this device if the client knows that the user is presently using the device (and thus would potentially see a notification immediately), even if the user has not directly interacted with the Zulip client. Otherwise, it should report the user as `"idle"`. See the related [`new_user_input`](#parameter-new_user_input) parameter for how a client should report whether the user is actively using the Zulip client. ' example: active required: - status responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false required: - result - msg properties: result: {} msg: {} ignored_parameters_unsupported: {} presence_last_update_id: type: integer description: 'The identifier for the latest user presence data returned in the `presences` data of the response. If a value was passed for `last_update_id`, then this is guaranteed to be equal to or greater than that value. If it is the same value, then that indicates to the client that there were no updates to previously received user presence data. The client should then pass this value as the `last_update_id` parameter when it next queries this endpoint, in order to only receive new user presence data and avoid redundantly fetching already known information. This will be `-1` if no value was passed for [`last_update_id`](#parameter-last_update_id) and no user presence data was returned by the server. This can happen, for example, if an organization has disabled presence. **Changes**: New in Zulip 9.0 (feature level 263). ' server_timestamp: type: number description: 'Only present if `ping_only` is `false`. The time when the server fetched the `presences` data included in the response. ' presences: type: object description: 'Only present if `ping_only` is `false`. A dictionary where each entry describes the presence details of a user in the Zulip organization. Entries can be in either the modern presence format or the legacy presence format. These entries will be the modern presence format when the `last_updated_id` parameter is passed, or when the deprecated `slim_presence` parameter is `true`. If the deprecated `slim_presence` parameter is `false` and the `last_updated_id` parameter is omitted, the entries will be in the legacy presence API format. **Note**: The legacy presence format should only be used when interacting with old servers. It will be removed as soon as doing so is practical. ' additionalProperties: description: 'Will be one of these two formats (modern or legacy) for user presence data: ' oneOf: - $ref: '#/components/schemas/ModernPresenceFormat' - type: object description: '`{user_email}`: Presence data (legacy format) for the user with the specified Zulip API email. ' additionalProperties: $ref: '#/components/schemas/LegacyPresenceFormat' examples: modern-presence-format-example: description: 'Modern presence format: ' value: msg: '' presences: '10': idle_timestamp: 1656958530 active_timestamp: 1656958520 result: success server_timestamp: 1656958539.6287155 presence_last_update_id: 1000 legacy-presence-format-example: description: 'Legacy presence format: ' value: msg: '' presences: user@example.com: aggregated: client: website status: idle timestamp: 1594825445 website: client: website status: idle timestamp: 1594825445 pushable: false result: success server_timestamp: 1656958539.6287155 presence_last_update_id: 1000 /users/me/profile_data: patch: operationId: update-profile-data summary: Update your profile data tags: - users description: 'Update the current user''s [profile data](/help/edit-your-profile) for one or more of the [custom profile fields](/help/custom-profile-fields) configured in the organization. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: data: description: 'An array of objects describing updates to the custom profile field data for the user. ' type: array example: - id: 4 value: '0' - id: 5 value: '1909-04-05' items: $ref: '#/components/schemas/ProfileDataUpdate' required: - data encoding: data: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: You are not allowed to change this field. Contact an administrator to update it. code: BAD_REQUEST description: 'An example JSON error response when editing custom profile fields is restricted in the organization: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Field id 99 not found. code: BAD_REQUEST description: 'An example JSON error response when a custom profile field ID does not exist: ' delete: operationId: remove-profile-data summary: Remove your profile data tags: - users description: 'Remove the current user''s [profile data](/help/edit-your-profile) for one or more of the [custom profile fields](/help/custom-profile-fields) configured in the organization. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: data: description: 'An array of custom profile field IDs to remove any data set for the user. ' type: array example: - 1 items: type: integer required: - data encoding: data: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: You are not allowed to change this field. Contact an administrator to update it. code: BAD_REQUEST description: 'An example JSON error response when editing custom profile fields is restricted in the organization: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Field id 99 not found. code: BAD_REQUEST description: 'An example JSON error response when a custom profile field ID does not exist: ' /users/me/status: post: operationId: update-status summary: Update your status tags: - users description: 'Change your [status](/help/status-and-availability). A request to this endpoint will only change the parameters passed. For example, passing just `status_text` requests a change in the status text, but will leave the status emoji unchanged. Clients that wish to set the user''s status to a specific value should pass all supported parameters. **Changes**: In Zulip 5.0 (feature level 86), added support for `emoji_name`, `emoji_code`, and `reaction_type` parameters. ' requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: status_text: type: string description: 'The text content of the status message. Sending the empty string will clear the user''s status. **Note**: The limit on the size of the message is 60 Unicode code points. ' example: on vacation away: deprecated: true type: boolean description: 'Whether the user should be marked as "away". **Changes**: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, `away` is a legacy way to access the user''s `presence_enabled` setting, with `away = !presence_enabled`. To be removed in a future release. ' example: true emoji_name: type: string description: 'The name for the emoji to associate with this status. **Changes**: New in Zulip 5.0 (feature level 86). ' example: car emoji_code: type: string description: 'A unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. **Changes**: New in Zulip 5.0 (feature level 86). ' example: 1f697 reaction_type: type: string description: "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" example: unicode_emoji encoding: away: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Client did not pass any new values. code: BAD_REQUEST description: 'An example JSON error response when no changes were requested: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: 'status_text is too long (limit: 60 characters)' code: BAD_REQUEST description: 'An example JSON error response when the `status_text` message exceeds the limit of 60 characters: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Client must pass emoji_name if they pass either emoji_code or reaction_type. code: BAD_REQUEST description: 'An example JSON error response when `emoji_name` is not specified but `emoji_code` or `reaction_type` is specified: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Emoji 'invalid' does not exist code: BAD_REQUEST description: 'An example JSON error response when the emoji name does not exist: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Invalid emoji name. code: BAD_REQUEST description: 'An example JSON error response when the emoji name is invalid: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Invalid custom emoji. code: BAD_REQUEST description: 'An example JSON error response when the custom emoji is invalid: ' /users/me/muted_users/{muted_user_id}: post: operationId: mute-user summary: Mute a user tags: - users description: "[Mute a user](/help/mute-a-user) from the perspective of the requesting\nuser. Messages sent by muted users will be automatically marked as read\nand hidden for the user who muted them.\n\nMuted users should be implemented by clients as follows:\n\n- The server will immediately mark all messages sent by the muted\n user as read. This will automatically clear any existing mobile\n push notifications related to the muted user.\n- The server will mark any new messages sent by the muted user as read\n for the requesting user's account, which prevents all email and mobile\n push notifications.\n- Clients should exclude muted users from presence lists or other UI\n for viewing or composing one-on-one direct messages. One-on-one direct\n messages sent by muted users should be hidden everywhere in the Zulip UI.\n- Channel messages and group direct messages sent by the muted\n user should avoid displaying the content and name/avatar,\n but should display that N messages by a muted user were\n hidden (so that it is possible to interpret the messages by\n other users who are talking with the muted user).\n- Group direct message conversations including the muted user\n should display muted users as \"Muted user\", rather than\n showing their name, in lists of such conversations, along with using\n a blank grey avatar where avatars are displayed.\n- Administrative/settings UI elements for showing \"All users that exist\n on this channel or realm\", e.g. for organization\n administration or showing channel subscribers, should display\n the user's name as normal.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n" parameters: - $ref: '#/components/parameters/MutedUserId' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Cannot mute self result: error description: 'An example JSON response for when the user ID is the current user''s ID: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: No such user result: error description: 'An example JSON response for when the user is nonexistent or inaccessible: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: User already muted result: error description: 'An example JSON response for when the user is already muted: ' delete: operationId: unmute-user summary: Unmute a user tags: - users description: '[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users) from the perspective of the requesting user. **Changes**: New in Zulip 4.0 (feature level 48). ' parameters: - $ref: '#/components/parameters/MutedUserId' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: No such user result: error description: 'An example JSON response for when the user is nonexistent or inaccessible: ' - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: User is not muted result: error description: 'An example JSON response for when the user is not previously muted: ' /users/me/apns_device_token: post: deprecated: true operationId: add-apns-token summary: Add an APNs device token tags: - users description: 'This endpoint adds an APNs device token to register for iOS push notifications. **Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting to newer servers and with E2EE push notifications support should use the [Register E2EE push device](/api/register-push-device) endpoint, as this endpoint will be removed in a future release. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: 'The token provided by the device. ' type: string example: c0ffee appid: description: 'The ID of the Zulip app that is making the request. **Changes**: In Zulip 8.0 (feature level 223), this parameter was made required. Previously, if it was unspecified, the server would use a default value (based on the `ZULIP_IOS_APP_ID` server setting, which defaulted to `"org.zulip.Zulip"`). ' type: string example: org.zulip.Zulip required: - token - appid responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - description: 'A typical failed JSON response for when the token''s length is invalid or it is empty: ' example: result: error msg: Empty or invalid length token code: BAD_REQUEST - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Invalid APNS token code: BAD_REQUEST description: 'A typical failed JSON response for when the APNs token is invalid: ' delete: deprecated: true operationId: remove-apns-token summary: Remove an APNs device token tags: - users description: 'This endpoint removes an APNs device token for iOS push notifications. **Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be removed in a future release. Clients connecting to newer servers and with E2EE push notifications support should delete the account record in their local accounts table that corresponds to the `push_account_id` supplied when registering via the [Register E2EE push device](/api/register-push-device) endpoint, to stop displaying notifications for that registration. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: 'The token provided by the device. ' type: string example: c0ffee required: - token responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - description: 'A typical failed JSON response for when the token''s length is invalid or it is empty: ' example: result: error msg: Empty or invalid length token code: BAD_REQUEST - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Token does not exist code: BAD_REQUEST description: 'A typical failed JSON response for when the token does not exist: ' /users/me/android_gcm_reg_id: post: deprecated: true operationId: add-fcm-token summary: Add an FCM registration token tags: - users description: 'This endpoint adds an FCM registration token for push notifications. **Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting to newer servers and with E2EE push notifications support should use the [Register E2EE push device](/api/register-push-device) endpoint, as this endpoint will be removed in a future release. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: 'The token provided by the device. ' type: string example: android-token required: - token responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - description: 'A typical failed JSON response for when the token''s length is invalid or is empty: ' example: result: error msg: Empty or invalid length token code: BAD_REQUEST delete: deprecated: true operationId: remove-fcm-token summary: Remove an FCM registration token tags: - users description: 'This endpoint removes an FCM registration token for push notifications. **Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be removed in a future release. Clients connecting to newer servers and with E2EE push notifications support should delete the account record in their local accounts table that corresponds to the `push_account_id` supplied when registering via the [Register E2EE push device](/api/register-push-device) endpoint, to stop displaying notifications for that registration. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: token: description: 'The token provided by the device. ' type: string example: android-token required: - token responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - description: 'A typical failed JSON response for when the token''s length is invalid or is empty: ' example: result: error msg: Empty or invalid length token code: BAD_REQUEST - allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Token does not exist code: BAD_REQUEST description: 'A typical failed JSON response for when the token does not exist: ' /users/{email}: get: operationId: get-user-by-email summary: Get a user by email tags: - users description: 'Fetch details for a single user in the organization given a Zulip API email address. You can also fetch details on [all users in the organization](/api/get-users) or [by user ID](/api/get-user). Fetching by user ID is generally recommended when possible, as a user might [change their email address](/help/change-your-email-address) or change their [email address visibility](/help/configure-email-visibility), either of which could change the client''s ability to look them up by that email address. **Changes**: In Zulip 12.0 (feature level 437), fixed a bug dating to feature level 232, which caused guest users to receive fake backwards-compatibility users in the format intended for clients using `POST /register` without the `user_list_incomplete` client capability. Starting with Zulip 10.0 (feature level 302), the real email address can be used in the `email` parameter and will fetch the target user''s data if and only if the target''s email visibility setting permits the requester to see the email address. The dummy email addresses of the form `user{id}@{realm.host}` still work, and will now work for **all** users, via identifying them by the embedded user ID. New in Zulip Server 4.0 (feature level 39). ' x-curl-examples-parameters: oneOf: - type: include parameters: enum: - '' - type: exclude parameters: enum: - '' description: 'You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows: ' parameters: - name: email in: path description: "The email address of the user to fetch. Two forms are supported:\n\n- The real email address of the user (`delivery_email`). The lookup will\n succeed if and only if the user exists and their email address visibility\n setting permits the client to see the email address.\n\n- The dummy Zulip API email address of the form `user{user_id}@{realm_host}`. This\n is identical to simply [getting user by ID](/api/get-user). If the server or\n realm change domains, the dummy email address used has to be adjustment to\n match the new realm domain. This is legacy behavior for\n backwards-compatibility, and will be removed in a future release.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), lookups by real email\naddress match the semantics of the target's email visibility setting and dummy\nemail addresses work for all users, independently of their email visibility\nsetting.\n\nPreviously, lookups were done only using the Zulip API email addresses.\n" schema: type: string example: iago@zulip.com required: true - $ref: '#/components/parameters/ClientGravatar' - $ref: '#/components/parameters/IncludeCustomProfileFields' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user: $ref: '#/components/schemas/User' example: msg: '' result: success user: date_joined: '2019-10-20T07:50:53.729659+00:00' full_name: King Hamlet is_guest: false profile_data: '4': value: '0' '2': value: 'I am: * The prince of Denmark * Nephew to the usurping Claudius' rendered_value: 'I am:
+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 delivery_email: null is_imported_stub: false patch: operationId: update-user-by-email summary: Update a user by email tags: - users x-requires-administrator: true description: 'Administrative endpoint to update the details of another user in the organization by their email address. Works the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their real email address. The requester needs to have permission to view the target user''s real email address, subject to the user''s email address visibility setting. Otherwise, the dummy address of the format `user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{email}`. **Changes**: New in Zulip 10.0 (feature level 313). ' parameters: - name: email in: path required: true description: 'The email address of the user, specified following the same rules as [`GET /users/{email}`](/api/get-user-by-email). ' schema: type: string example: hamlet@zulip.com requestBody: $ref: '#/components/requestBodies/UpdateUser' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Guests cannot be organization administrators code: BAD_REQUEST description: 'A typical unsuccessful JSON response: ' /users/{user_id}: get: operationId: get-user summary: Get a user tags: - users description: 'Fetch details for a single user in the organization. You can also fetch details on [all users in the organization](/api/get-users) or [by a user''s Zulip API email](/api/get-user-by-email). **Changes**: In Zulip 12.0 (feature level 437), fixed a bug dating to feature level 232, which caused guest users to receive fake backwards-compatibility users in the format intended for clients using `POST /register` without the `user_list_incomplete` client capability. New in Zulip 3.0 (feature level 1). ' x-curl-examples-parameters: oneOf: - type: include parameters: enum: - '' - type: exclude parameters: enum: - '' description: 'You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows: ' parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/ClientGravatar' - $ref: '#/components/parameters/IncludeCustomProfileFields' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user: $ref: '#/components/schemas/User' example: msg: '' result: success user: date_joined: '2019-10-20T07:50:53.729659+00:00' full_name: King Hamlet is_guest: false profile_data: '4': value: '0' '2': value: 'I am: * The prince of Denmark * Nephew to the usurping Claudius' rendered_value: 'I am:
+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 delivery_email: null is_imported_stub: false patch: operationId: update-user summary: Update a user tags: - users x-requires-administrator: true description: 'Administrative endpoint to update the details of another user in the organization. Supports everything an administrator can do to edit details of another user''s account, including editing full name, [role](/help/user-roles), and [custom profile fields](/help/custom-profile-fields). ' parameters: - $ref: '#/components/parameters/UserId' requestBody: $ref: '#/components/requestBodies/UpdateUser' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: result: error msg: Guests cannot be organization administrators code: BAD_REQUEST description: 'A typical unsuccessful JSON response: ' delete: operationId: deactivate-user summary: Deactivate a user tags: - users x-requires-administrator: true description: '[Deactivates a user](https://zulip.com/help/deactivate-or-reactivate-a-user) given their user ID. Note that any bots controlled by the user will be deactivated before the user; clients that don''t want this behavior are expected to prompt the user to adjust the bot''s owners before making this API request. ' parameters: - $ref: '#/components/parameters/UserId' - name: actions in: query description: 'Additional actions for the server to perform while deactivating the user. As with the actual deactivation, actions are first applied to any bots controlled by the target user, and then to the target user. **Changes**: New in Zulip 12.0 (feature level 459). ' content: application/json: schema: type: object properties: delete_profile: type: boolean description: 'Whether to delete the user''s profile by updating their name to "Deleted user" and removing their profile picture. ' delete_public_channel_messages: type: boolean description: Whether to delete messages in public channels. delete_private_channel_messages: type: boolean description: Whether to delete messages in private channels. delete_direct_messages: type: boolean description: Whether to delete direct messages. example: delete_profile: false delete_public_channel_messages: false delete_private_channel_messages: false delete_direct_messages: false required: false requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: deactivation_notification_comment: description: 'If not `null`, requests that the deactivated user receive a notification email about their account deactivation. If not `""`, encodes custom text written by the administrator to be included in the notification email. **Changes**: New in Zulip 5.0 (feature level 135). ' type: string example: 'Farewell! ' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Cannot deactivate the only organization owner result: error description: 'An example JSON error response when attempting to deactivate the only organization owner in an organization: ' /settings: patch: operationId: update-settings summary: Update settings tags: - users description: 'This endpoint is used to edit the current user''s settings. When invoked by a realm admin, it supports bulk updates to settings for specified users or members of user groups using the `target_users` parameter. **Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364) as we now have `web_font_size_px` and `web_line_height_percent` settings for more control. Prior to Zulip 5.0 (feature level 80), this endpoint only supported the `full_name`, `email`, `old_password`, and `new_password` parameters. Notification settings were managed by `PATCH /settings/notifications`, and all other settings by `PATCH /settings/display`. The feature level 80 migration to merge these endpoints did not change how request parameters are encoded. However, it did change the handling of any invalid parameters present in a request (see feature level 78 change below). As of feature level 80, the `PATCH /settings/display` and `PATCH /settings/notifications` endpoints are deprecated aliases for this endpoint for backwards-compatibility, and will be removed once clients have migrated to use this endpoint. Prior to Zulip 5.0 (feature level 78), this endpoint indicated which parameters it had processed by including in the response object `"key": value` entries for values successfully changed by the request. That was replaced by the more ergonomic [`ignored_parameters_unsupported`][ignored-parameters] array. The `PATCH /settings/notifications` and `PATCH /settings/display` endpoints also had this behavior of indicating processed parameters before they became aliases of this endpoint in Zulip 5.0 (see feature level 80 change above). Before feature level 78, request parameters that were not supported (or were unchanged) were silently ignored. [ignored-parameters]: /api/rest-error-handling#ignored-parameters ' x-curl-examples-parameters: oneOf: - type: include parameters: enum: - left_side_userlist - emojiset requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: target_users: description: 'An object specifying the collection of users whose settings should be modified, for modification of other users'' settings by an organization administrator. When this parameter is absent, this API endpoint always modifies the current user''s own settings. **Changes**: New in Zulip 12.0 (feature level 444). ' type: object properties: user_ids: description: 'A list of integer user IDs representing individual users whose settings will be updated. ' type: array items: type: integer group_ids: description: 'A list of integer group IDs representing user groups, where settings will be applied to all active members of the specified groups. ' type: array items: type: integer skip_if_already_edited: description: 'Whether to skip editing the settings of users who have previously edited their settings, which can be useful for adjusting a default without overriding users'' own directly expressed preferences. ' type: boolean example: false example: user_ids: - 6 - 8 group_ids: - 24 skip_if_already_edited: false full_name: description: 'A new display name for the user. ' type: string example: NewName email: description: 'Asks the server to initiate a confirmation sequence to change the user''s email address to the indicated value. The user will need to demonstrate control of the new email address by clicking a confirmation link sent to that address. ' type: string example: newname@example.com old_password: description: 'The user''s old Zulip password (or LDAP password, if LDAP authentication is in use). Required only when sending the `new_password` parameter. ' type: string example: old12345 new_password: description: 'The user''s new Zulip password (or LDAP password, if LDAP authentication is in use). The `old_password` parameter must be included in the request. ' type: string example: new12345 twenty_four_hour_time: description: 'Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true web_mark_read_on_scroll_policy: description: 'Whether or not to mark messages as read when the user scrolls through their feed. - 1 - Always - 2 - Only in conversation views - 3 - Never **Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read. ' type: integer enum: - 1 - 2 - 3 example: 1 web_channel_default_view: description: 'Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed - 3 - List of topics - 4 - Top unread topic in channel **Changes**: The "Top unread topic in channel" is new in Zulip 11.0 (feature level 401). The "List of topics" option is new in Zulip 11.0 (feature level 383). New in Zulip 9.0 (feature level 269). Previously, this was not configurable, and every user had the "Channel feed" behavior. ' type: integer enum: - 1 - 2 - 4 example: 1 starred_message_counts: description: 'Whether clients should display the [number of starred messages](/help/star-a-message#display-the-number-of-starred-messages). **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true receives_typing_notifications: description: 'Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. By default, this is set to true, enabling user to receive typing notifications from other users. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. ' type: boolean example: true web_suggest_update_timezone: type: boolean description: 'Whether the user should be shown an alert, offering to update their [profile time zone](/help/change-your-timezone), when the time displayed for the profile time zone differs from the current time displayed by the time zone configured on their device. **Changes**: New in Zulip 10.0 (feature level 329). ' example: true fluid_layout_width: description: 'Whether to use the [maximum available screen width](/help/enable-full-width-display) for the web app''s center panel (message feed, recent conversations) on wide screens. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true high_contrast_mode: description: 'This setting is reserved for use to control variations in Zulip''s design to help visually impaired users. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true web_font_size_px: description: 'User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. ' type: integer example: 14 web_line_height_percent: description: 'User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. ' type: integer example: 122 color_scheme: description: 'Controls which [color theme](/help/dark-theme) to use. - 1 - Automatic - 2 - Dark theme - 3 - Light theme Automatic detection is implementing using the standard `prefers-color-scheme` media query. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: integer enum: - 1 - 2 - 3 example: 1 enable_drafts_synchronization: description: 'A boolean parameter to control whether synchronizing drafts is enabled for the user. When synchronization is disabled, all drafts stored in the server will be automatically deleted from the server. This does not do anything (like sending events) to delete local copies of drafts stored in clients. **Changes**: New in Zulip 5.0 (feature level 87). ' type: boolean example: true translate_emoticons: description: 'Whether to [translate emoticons to emoji](/help/configure-emoticon-translations) in messages the user sends. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true display_emoji_reaction_users: description: 'Whether to display the names of reacting users on a message. When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled. **Changes**: New in Zulip 6.0 (feature level 125). ' type: boolean example: false default_language: description: 'What [default language](/help/change-your-language) to use for the account. This controls both the Zulip UI as well as email notifications sent to the user. The value needs to be a standard language code that the Zulip server has translation data for; for example, `"en"` for English or `"de"` for German. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63). ' type: string example: en web_home_view: description: 'The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent" - Recent conversations view - "inbox" - Inbox view - "all_messages" - Combined feed view **Changes**: Before Zulip 12.0 (feature level 454), the Recent view had `"recent_topics"` as its string encoding. New in Zulip 8.0 (feature level 219). Previously, this was called `default_view`, which was new in Zulip 4.0 (feature level 42). Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). ' type: string example: all_messages web_escape_navigates_to_home_view: description: 'Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107). ' type: boolean example: true left_side_userlist: description: 'Whether the users list on left sidebar in narrow windows. This feature is not heavily used and is likely to be reworked. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: boolean example: true emojiset: description: 'The user''s configured [emoji set](/help/emoji-and-emoticons#use-emoticons), used to display emoji to the user everywhere they appear in the UI. - "google" - Google modern - "twitter" - Twitter - "text" - Plain text **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). ' type: string example: google demote_inactive_streams: description: 'Whether to [hide inactive channels](/help/manage-inactive-channels) in the left sidebar. - 1 - Automatic - 2 - Always - 3 - Never **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. ' type: integer enum: - 1 - 2 - 3 example: 1 user_list_style: description: 'The style selected by the user for the right sidebar user list. - 1 - Compact - 2 - With status - 3 - With avatar and status **Changes**: New in Zulip 6.0 (feature level 141). ' type: integer enum: - 1 - 2 - 3 example: 1 web_animate_image_previews: description: 'Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). ' type: string enum: - always - on_hover - never example: on_hover web_stream_unreads_count_display_policy: description: 'Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). ' type: integer enum: - 1 - 2 - 3 example: 2 hide_ai_features: type: boolean description: 'Controls whether user wants AI features like topic summarization to be hidden in all Zulip clients. **Changes**: New in Zulip 10.0 (feature level 350). ' web_inbox_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how conversations with unread messages are displayed in the web/desktop application''s Inbox view. **Changes**: New in Zulip 12.0 (feature level 431). ' web_left_sidebar_show_channel_folders: type: boolean description: 'Determines whether [channel folders](/help/channel-folders) are used to organize how channels are displayed in the web/desktop application''s left sidebar. **Changes**: New in Zulip 11.0 (feature level 411). ' example: true web_left_sidebar_unreads_count_summary: description: 'Determines whether the web/desktop application''s left sidebar displays the unread message count summary. **Changes**: New in Zulip 11.0 (feature level 398). ' type: boolean example: true timezone: description: 'The IANA identifier of the user''s [profile time zone](/help/change-your-timezone), which is used primarily to display the user''s local time to other users. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/display` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64). ' type: string example: Asia/Kolkata enable_stream_desktop_notifications: description: 'Enable visual desktop notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_stream_email_notifications: description: 'Enable email notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_stream_push_notifications: description: 'Enable mobile notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_stream_audible_notifications: description: 'Enable audible desktop notifications for channel messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true notification_sound: description: 'Notification sound name. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63). ' type: string example: ding enable_desktop_notifications: description: 'Enable visual desktop notifications for direct messages and @-mentions. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_sounds: description: 'Enable audible desktop notifications for direct messages and @-mentions. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true email_notifications_batching_period_seconds: description: 'The duration (in seconds) for which the server should wait to batch email notifications before sending them. **Changes**: New in Zulip 5.0 (feature level 82) ' type: integer example: 120 enable_offline_email_notifications: description: 'Enable email notifications for direct messages and @-mentions received when the user is offline. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_offline_push_notifications: description: 'Enable mobile notification for direct messages and @-mentions received when the user is offline. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_online_push_notifications: description: 'Enable mobile notification for direct messages and @-mentions received when the user is online. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_followed_topic_desktop_notifications: description: 'Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true enable_followed_topic_email_notifications: description: 'Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true enable_followed_topic_push_notifications: description: 'Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: false enable_followed_topic_audible_notifications: description: 'Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: false enable_digest_emails: description: 'Enable digest emails when the user is away. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_marketing_emails: description: 'Enable marketing emails. Has no function outside Zulip Cloud. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_login_emails: description: 'Enable email notifications for new logins to account. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true message_content_in_email_notifications: description: 'Include the message''s content in email notifications for new messages. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true pm_content_in_desktop_notifications: description: 'Include content of direct messages in desktop notifications. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true wildcard_mentions_notify: description: 'Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enable_followed_topic_wildcard_mentions_notify: description: 'Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true desktop_icon_count_display: description: 'Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 realm_name_in_email_notifications_policy: description: 'Whether to [include organization name in subject of message notification emails](/help/email-notifications#include-organization-name-in-subject-line). - 1 - Automatic - 2 - Always - 3 - Never **Changes**: New in Zulip 7.0 (feature level 168), replacing the previous `realm_name_in_notifications` boolean; `true` corresponded to `Always`, and `false` to `Never`. Before Zulip 5.0 (feature level 80), the previous `realm_name_in_notifications` setting was managed by the `PATCH /settings/notifications` endpoint. ' type: integer enum: - 1 - 2 - 3 example: 1 automatically_follow_topics_policy: description: 'Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_unmute_topics_in_muted_streams_policy: description: 'Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_follow_topics_where_mentioned: description: 'Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). ' type: boolean example: true resolved_topic_notice_auto_read_policy: description: 'Controls whether the resolved-topic notices are marked as read. - "always" - Always mark resolved-topic notices as read. - "except_followed" - Mark resolved-topic notices as read in topics not followed by the user. - "never" - Never mark resolved-topic notices as read. **Changes**: New in Zulip 11.0 (feature level 385). ' type: string enum: - always - except_followed - never example: except_followed presence_enabled: description: 'Display the presence status to other users when online. **Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by the `PATCH /settings/notifications` endpoint. ' type: boolean example: true enter_sends: description: 'Whether pressing Enter in the compose box sends a message (or saves a message edit). **Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by the `POST /users/me/enter-sends` endpoint, with the same parameter format. ' type: boolean example: true send_private_typing_notifications: description: 'Whether [typing notifications](/help/typing-notifications) be sent when composing direct messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true send_stream_typing_notifications: description: 'Whether [typing notifications](/help/typing-notifications) be sent when composing channel messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true send_read_receipts: description: 'Whether other users are allowed to see whether you''ve read messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true allow_private_data_export: description: 'Whether organization administrators are allowed to export your private data. **Changes**: New in Zulip 10.0 (feature level 293). ' type: boolean example: true email_address_visibility: description: 'The [policy][permission-level] this user has selected for [which other users][help-email-visibility] in this organization can see their real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility ' type: integer enum: - 1 - 2 - 3 - 4 - 5 example: 1 web_navigate_to_sent_message: description: 'Web/desktop app setting for whether the user''s view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. ' type: boolean example: true encoding: target_users: contentType: application/json twenty_four_hour_time: contentType: application/json web_mark_read_on_scroll_policy: contentType: application/json web_channel_default_view: contentType: application/json starred_message_counts: contentType: application/json receives_typing_notifications: contentType: application/json web_suggest_update_timezone: contentType: application/json fluid_layout_width: contentType: application/json high_contrast_mode: contentType: application/json web_font_size_px: contentType: application/json web_line_height_percent: contentType: application/json color_scheme: contentType: application/json enable_drafts_synchronization: contentType: application/json translate_emoticons: contentType: application/json display_emoji_reaction_users: contentType: application/json web_escape_navigates_to_home_view: contentType: application/json left_side_userlist: contentType: application/json demote_inactive_streams: contentType: application/json user_list_style: contentType: application/json web_stream_unreads_count_display_policy: contentType: application/json hide_ai_features: contentType: application/json web_inbox_show_channel_folders: contentType: application/json web_left_sidebar_show_channel_folders: contentType: application/json web_left_sidebar_unreads_count_summary: contentType: application/json enable_stream_desktop_notifications: contentType: application/json enable_stream_email_notifications: contentType: application/json enable_stream_push_notifications: contentType: application/json enable_stream_audible_notifications: contentType: application/json enable_desktop_notifications: contentType: application/json enable_sounds: contentType: application/json email_notifications_batching_period_seconds: contentType: application/json enable_offline_email_notifications: contentType: application/json enable_offline_push_notifications: contentType: application/json enable_online_push_notifications: contentType: application/json enable_followed_topic_desktop_notifications: contentType: application/json enable_followed_topic_email_notifications: contentType: application/json enable_followed_topic_push_notifications: contentType: application/json enable_followed_topic_audible_notifications: contentType: application/json enable_digest_emails: contentType: application/json enable_marketing_emails: contentType: application/json enable_login_emails: contentType: application/json message_content_in_email_notifications: contentType: application/json pm_content_in_desktop_notifications: contentType: application/json wildcard_mentions_notify: contentType: application/json enable_followed_topic_wildcard_mentions_notify: contentType: application/json desktop_icon_count_display: contentType: application/json realm_name_in_email_notifications_policy: contentType: application/json automatically_follow_topics_policy: contentType: application/json automatically_unmute_topics_in_muted_streams_policy: contentType: application/json automatically_follow_topics_where_mentioned: contentType: application/json presence_enabled: contentType: application/json enter_sends: contentType: application/json send_private_typing_notifications: contentType: application/json send_stream_typing_notifications: contentType: application/json send_read_receipts: contentType: application/json allow_private_data_export: contentType: application/json email_address_visibility: contentType: application/json web_navigate_to_sent_message: contentType: application/json responses: '200': $ref: '#/components/responses/SuccessIgnoredParameters' /typing: post: operationId: set-typing-status summary: Set "typing" status tags: - users description: "Notify other users whether the current user is\n[typing a message][help-typing].\n\nClients implementing Zulip's typing notifications\nprotocol should work as follows:\n\n- Send a request to this endpoint with `\"op\": \"start\"` when a user\n starts composing a message.\n- While the user continues to actively type or otherwise interact with\n the compose UI (e.g. interacting with the compose box emoji picker),\n send regular `\"op\": \"start\"` requests to this endpoint, using\n `server_typing_started_wait_period_milliseconds` in the\n [`POST /register`][api-register] response as the time interval\n between each request.\n- Send a request to this endpoint with `\"op\": \"stop\"` when a user\n has stopped using the compose UI for the time period indicated by\n `server_typing_stopped_wait_period_milliseconds` in the\n [`POST /register`][api-register] response or when a user\n cancels the compose action (if it had previously sent a \"start\"\n notification for that compose action).\n- Start displaying a visual typing indicator for a given conversation\n when a [`typing op:start`][start-typing] event is received\n from the server.\n- Continue displaying a visual typing indicator for the conversation\n until a [`typing op:stop`][stop-typing] event is received\n from the server or the time period indicated by\n `server_typing_started_expiry_period_milliseconds` in the\n [`POST /register`][api-register] response has passed without\n a new `typing \"op\": \"start\"` event for the conversation.\n\nThis protocol is designed to allow the server-side typing notifications\nimplementation to be stateless while being resilient as network failures\nwill not result in a user being incorrectly displayed as perpetually\ntyping.\n\nSee the subsystems documentation on [typing indicators][typing-protocol-docs]\nfor additional design details on Zulip's typing notifications protocol.\n\n**Changes**: Clients shouldn't care about the APIs prior to Zulip 8.0 (feature level 215)\nfor channel typing notifications, as no client actually implemented\nthe previous API for those.\n\nSupport for displaying channel typing notifications was new\nin Zulip 4.0 (feature level 58). Clients should indicate they support\nprocessing channel typing notifications via the `stream_typing_notifications`\nvalue in the `client_capabilities` parameter of the\n[`POST /register`][client-capabilities] endpoint.\n\n[help-typing]: /help/typing-notifications\n[api-register]: /api/register-queue\n[start-typing]: /api/get-events#typing-start\n[stop-typing]: /api/get-events#typing-stop\n[client-capabilities]: /api/register-queue#parameter-client_capabilities\n[typing-protocol-docs]: https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html\n" x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - topic requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: type: description: 'Type of the message being composed. **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as an additional value for this parameter to indicate a channel message is being composed. In Zulip 8.0 (feature level 215), stopped supporting `"private"` as a valid value for this parameter. In Zulip 7.0 (feature level 174), `"direct"` was added as the preferred way to indicate a direct message is being composed, becoming the default value for this parameter and deprecating the original `"private"`. New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. ' type: string enum: - direct - stream - channel default: direct example: direct op: description: 'Whether the user has started (`"start"`) or stopped (`"stop"`) typing. ' type: string enum: - start - stop example: start to: description: 'User IDs of the recipients of the message being typed. Required for the `"direct"` type. Ignored in the case of `"stream"` or `"channel"` type. Clients should send a JSON-encoded list of user IDs, even if there is only one recipient. **Changes**: In Zulip 8.0 (feature level 215), stopped using this parameter for the `"stream"` type. Previously, in the case of the `"stream"` type, it accepted a single-element list containing the ID of the channel. A new parameter, `stream_id`, is now used for this. Note that the `"channel"` type did not exist at this feature level. Support for typing notifications for channel'' messages is new in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. Before Zulip 2.0.0, this parameter accepted only a JSON-encoded list of email addresses. Support for the email address-based format was removed in Zulip 3.0 (feature level 11). ' type: array items: type: integer minLength: 1 example: - 9 - 10 stream_id: description: 'ID of the channel in which the message is being typed. Required for the `"stream"` or `"channel"` type. Ignored in the case of `"direct"` type. **Changes**: New in Zulip 8.0 (feature level 215). Previously, a single-element list containing the ID of the channel was passed in `to` parameter. ' type: integer example: 7 topic: description: 'Topic to which message is being typed. Required for the `"stream"` or `"channel"` type. Ignored in the case of `"direct"` type. Note: When `"(no topic)"` or the value of `realm_empty_topic_display_name` found in the [POST /register](/api/register-queue) response is used for this parameter, it is interpreted as an empty string. **Changes**: Before Zulip 10.0 (feature level 372), `"(no topic)"` was not interpreted as an empty string. Before Zulip 10.0 (feature level 334), empty string was not a valid topic name for channel messages. New in Zulip 4.0 (feature level 58). Previously, typing notifications were only for direct messages. ' type: string example: typing notifications required: - op encoding: to: contentType: application/json stream_id: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Missing channel ID result: error description: 'An example JSON error response when the user composes a channel message and `stream_id` is not specified: ' /messages/{message_id}/typing: post: operationId: set-typing-status-for-message-edit summary: Set "typing" status for message editing tags: - users description: 'Notify other users whether the current user is editing a message. Typing notifications for editing messages follow the same protocol as [set-typing-status](/api/set-typing-status), see that endpoint for details. **Changes**: Before Zulip 10.0 (feature level 361), the endpoint was named `/message_edit_typing` with `message_id` a required parameter in the request body. Clients are recommended to start using sending these typing notifications starting from this feature level. New in Zulip 10.0 (feature level 351). Previously, typing notifications were not available when editing messages. ' parameters: - name: message_id in: path description: 'The target message''s ID. ' schema: type: integer example: 47 required: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: op: description: 'Whether the user has started (`"start"`) or stopped (`"stop"`) editing. ' type: string enum: - start - stop example: start required: - op responses: '200': $ref: '#/components/responses/SimpleSuccess' /user_groups/create: post: operationId: create-user-group summary: Create a user group tags: - users description: 'Create a new [user group](/help/user-groups). **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: description: 'The name of the user group. ' type: string example: marketing description: description: 'The description of the user group. ' type: string example: The marketing team. members: description: 'An array containing the user IDs of the initial members for the new user group. ' type: array items: type: integer example: - 1 - 2 - 3 - 4 subgroups: description: 'An array containing the IDs of the initial subgroups for the new user group. User can add subgroups to the new group irrespective of other permissions for the new group. **Changes**: New in Zulip 10.0 (feature level 311). ' type: array items: type: integer example: - 11 can_add_members_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups ' - $ref: '#/components/schemas/GroupSettingValue' example: 11 can_join_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups ' - $ref: '#/components/schemas/GroupSettingValue' example: 11 can_leave_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups ' - $ref: '#/components/schemas/GroupSettingValue' example: 15 can_manage_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. This setting cannot be set to `"role:internet"` and `"role:everyone"` [system groups][system-groups]. **Changes**: New in Zulip 10.0 (feature level 283). [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [manage-user-groups]: /help/manage-user-groups ' - $ref: '#/components/schemas/GroupSettingValue' example: 11 can_mention_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. This setting cannot be set to `"role:internet"` and `"role:owners"` [system groups][system-groups]. Before Zulip 9.0 (feature level 258), this parameter could only be the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this parameter was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group ' - $ref: '#/components/schemas/GroupSettingValue' example: 11 can_remove_members_group: allOf: - description: 'A [group-setting value][setting-values] defining the set of users who have permission to remove members from this user group. **Changes**: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the `can_manage_group` setting. [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups ' - $ref: '#/components/schemas/GroupSettingValue' example: 11 required: - name - description - members encoding: members: contentType: application/json subgroups: contentType: application/json can_add_members_group: contentType: application/json can_join_group: contentType: application/json can_leave_group: contentType: application/json can_manage_group: contentType: application/json can_mention_group: contentType: application/json can_remove_members_group: contentType: application/json responses: '200': description: 'A success response containing the unique ID of the user group. This field provides a straightforward way to reference the newly created user group. **Changes**: New in Zulip 10.0 (feature level 317). ' content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - required: - group_id additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} group_id: type: integer description: 'The unique ID of the created user group. ' example: msg: '' result: success group_id: 123 '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: result: error code: BAD_REQUEST msg: 'Invalid user ID: 500' description: 'An example JSON error response for when the one of the users does not exist: ' /user_groups/{user_group_id}/members: post: operationId: update-user-group-members summary: Update user group members tags: - users description: 'Update the members of a [user group](/help/user-groups). The user IDs must correspond to non-deactivated users. **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. Prior to Zulip 11.0 (feature level 391), members could not be added or removed from a deactivated group. **Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of deactivated users were visible to the API and could be edited via this endpoint. ' x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - delete parameters: - $ref: '#/components/parameters/UserGroupId' requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: delete: description: 'The list of user IDs to be removed from the user group. ' type: array items: type: integer example: - 10 add: description: 'The list of user IDs to be added to the user group. ' type: array items: type: integer example: - 12 - 13 delete_subgroups: description: 'The list of user group IDs to be removed from the user group. **Changes**: New in Zulip 10.0 (feature level 311). ' type: array items: type: integer example: - 9 add_subgroups: description: 'The list of user group IDs to be added to the user group. **Changes**: New in Zulip 10.0 (feature level 311). ' type: array items: type: integer example: - 9 encoding: delete: contentType: application/json add: contentType: application/json delete_subgroups: contentType: application/json add_subgroups: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' get: operationId: get-user-group-members summary: Get user group members tags: - users description: 'Get the members of a [user group](/help/user-groups). **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. New in Zulip 6.0 (feature level 127). ' parameters: - $ref: '#/components/parameters/UserGroupId' - $ref: '#/components/parameters/DirectMemberOnly' responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} members: type: array items: type: integer description: 'A list containing the user IDs of members of the user group. ' example: msg: '' result: success members: - 10 - 12 /user_groups/{user_group_id}: patch: operationId: update-user-group summary: Update a user group tags: - users description: 'Update the name, description or any of the permission settings of a [user group](/help/user-groups). This endpoint is also used to reactivate a user group. Note that while permissions settings of deactivated groups can be edited by this API endpoint, and those permissions settings do affect the ability to modify the deactivated group and its membership, the deactivated group itself cannot be mentioned or used in the value of any permission without first being reactivated. **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. Starting with Zulip 11.0 (feature level 386), this endpoint can be used to reactivate a user group. Prior to Zulip 10.0 (feature level 340), only the name field of deactivated groups could be modified. ' parameters: - $ref: '#/components/parameters/UserGroupId' requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: name: description: 'The new name of the group. **Changes**: Before Zulip 7.0 (feature level 165), this was a required field. ' type: string example: marketing team description: description: 'The new description of the group. **Changes**: Before Zulip 7.0 (feature level 165), this was a required field. ' type: string example: The marketing team. can_add_members_group: allOf: - description: 'The set of users who have permission to add members to this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 11 - $ref: '#/components/schemas/GroupSettingValueUpdate' can_join_group: allOf: - description: 'The set of users who have permission to join this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 301). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 11 - $ref: '#/components/schemas/GroupSettingValueUpdate' can_leave_group: allOf: - description: 'The set of users who have permission to leave this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 308). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 15 - $ref: '#/components/schemas/GroupSettingValueUpdate' can_manage_group: allOf: - description: 'The set of users who have permission to [manage this user group][manage-user-groups] expressed as an [update to a group-setting value][update-group-setting]. This setting cannot be set to `"role:internet"` and `"role:everyone"` [system groups][system-groups]. **Changes**: New in Zulip 10.0 (feature level 283). [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups [manage-user-groups]: /help/manage-user-groups ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 11 - $ref: '#/components/schemas/GroupSettingValueUpdate' can_mention_group: allOf: - description: 'The set of users who have permission to [mention this group][mentions], expressed as an [update to a group-setting value][update-group-setting]. This setting cannot be set to `"role:internet"` and `"role:owners"` [system groups][system-groups]. **Changes**: In Zulip 9.0 (feature level 260), this parameter was updated to only accept an object with the `old` and `new` fields described below. Prior to this feature level, this parameter could be either of the two forms of a [group-setting value][setting-values]. Before Zulip 9.0 (feature level 258), this parameter could only be the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this parameter was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. [mentions]: /help/mention-a-user-or-group [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups [setting-values]: /api/group-setting-values ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 11 - $ref: '#/components/schemas/GroupSettingValueUpdate' can_remove_members_group: allOf: - description: 'The set of users who have permission to remove members from this user group expressed as an [update to a group-setting value][update-group-setting]. **Changes**: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the `can_manage_group` setting. [update-group-setting]: /api/group-setting-values#updating-group-setting-values [system-groups]: /api/group-setting-values#system-groups ' example: new: direct_members: - 10 direct_subgroups: - 11 old: 11 - $ref: '#/components/schemas/GroupSettingValueUpdate' deactivated: description: 'A deactivated user group can be reactivated by passing this parameter as `false`. Passing `true` does nothing as user group is deactivated using [`POST /user_groups/{user_group_id}/deactivate`](deactivate-user-group) endpoint. **Changes**: New in Zulip 11.0 (feature level 386). ' type: boolean example: false encoding: can_add_members_group: contentType: application/json can_join_group: contentType: application/json can_leave_group: contentType: application/json can_manage_group: contentType: application/json can_mention_group: contentType: application/json can_remove_members_group: contentType: application/json deactivated: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Invalid user group result: error description: 'An example JSON response when the user group ID is invalid: ' /user_groups: get: operationId: get-user-groups summary: Get user groups tags: - users description: "Fetches all of the user groups in the organization.\n\n!!! warn \"\"\n\n **Note**: This endpoint is not available to\n [guest users](/help/user-roles).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: include_deactivated_groups: description: 'Whether to include deactivated user groups in the response. **Changes**: In Zulip 10.0 (feature level 294), renamed `allow_deactivated` to `include_deactivated_groups`. New in Zulip 10.0 (feature level 290). Previously, deactivated user groups did not exist and thus would never be included in the response. ' type: boolean example: true default: false encoding: include_deactivated_groups: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} user_groups: type: array items: type: object additionalProperties: false properties: description: type: string description: 'The human-readable description of the user group. ' id: type: integer description: 'The user group''s integer ID. ' date_created: type: integer nullable: true description: 'The UNIX timestamp for when the user group was created, in UTC seconds. A `null` value means the user group has no recorded date, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' creator_id: type: integer nullable: true description: 'The ID of the user who created this user group. A `null` value means the user group has no recorded creator, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or [management command][management-commands]. **Changes**: New in Zulip 10.0 (feature level 292). [management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html ' members: type: array description: 'The integer user IDs of the user group''s members, which are guaranteed to be non-deactivated users in the organization. **Changes**: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated. ' items: type: integer direct_subgroup_ids: type: array description: 'The integer user group IDs of the direct subgroups. **Changes**: New in Zulip 6.0 (feature level 131). Introduced in feature level 127 as `subgroups`, but clients can ignore older events as this feature level predates subgroups being fully implemented. ' items: type: integer name: type: string description: 'User group name. ' is_system_group: type: boolean description: 'Whether the user group is a system group which cannot be modified by users. **Changes**: New in Zulip 5.0 (feature level 93). ' can_add_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to add members to this user group. **Changes**: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' can_join_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to join this user group. **Changes**: New in Zulip 10.0 (feature level 301). Will be one of the following: [setting-values]: /api/group-setting-values ' can_leave_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to leave this user group. **Changes**: New in Zulip 10.0 (feature level 308). Will be one of the following: [setting-values]: /api/group-setting-values ' can_manage_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [manage this user group][manage-user-groups]. **Changes**: New in Zulip 10.0 (feature level 283). Will be one of the following: [setting-values]: /api/group-setting-values [manage-user-groups]: /help/manage-user-groups ' can_mention_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to [mention this user group][mentions]. **Changes**: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a [group-setting value][setting-values]. Before Zulip 8.0 (feature level 198), this setting was named `can_mention_group_id`. New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not [system groups][system-groups]. Will be one of the following: [setting-values]: /api/group-setting-values [system-groups]: /api/group-setting-values#system-groups [mentions]: /help/mention-a-user-or-group ' can_remove_members_group: allOf: - $ref: '#/components/schemas/GroupSettingValue' - description: 'A [group-setting value][setting-values] defining the set of users who have permission to remove members from this user group. **Changes**: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the `can_manage_group` setting. Will be one of the following: [setting-values]: /api/group-setting-values ' deactivated: type: boolean description: 'Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose. **Changes**: New in Zulip 10.0 (feature level 290). ' description: 'A list of `user_group` objects. ' example: msg: '' result: success user_groups: - description: Owners of this organization id: 1 creator_id: null date_created: null name: role:owners members: - 1 direct_subgroup_ids: [] is_system_group: true can_add_members_group: 16 can_join_group: 16 can_leave_group: 15 can_manage_group: 16 can_mention_group: 11 can_remove_members_group: 16 - description: Administrators of this organization, including owners id: 2 creator_id: null date_created: null name: role:administrators members: - 2 direct_subgroup_ids: - 1 is_system_group: true can_add_members_group: 17 can_join_group: 17 can_leave_group: 15 can_manage_group: 17 can_mention_group: 12 can_remove_members_group: 16 - description: Characters of Hamlet id: 3 creator_id: null date_created: 1717484476 name: hamletcharacters members: - 3 - 4 direct_subgroup_ids: [] is_system_group: false can_add_members_group: 20 can_join_group: 20 can_leave_group: 15 can_manage_group: 20 can_mention_group: 13 can_remove_members_group: 16 /user_groups/{user_group_id}/subgroups: post: operationId: update-user-group-subgroups summary: Update subgroups of a user group tags: - users description: 'Update the subgroups of a [user group](/help/user-groups). **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. Prior to Zulip 11.0 (feature level 391), subgroups could not be added or removed from a deactivated group. New in Zulip 6.0 (feature level 127). ' x-curl-examples-parameters: oneOf: - type: exclude parameters: enum: - delete parameters: - $ref: '#/components/parameters/UserGroupId' requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: delete: description: 'The list of user group IDs to be removed from the user group. ' type: array items: type: integer example: - 10 add: description: 'The list of user group IDs to be added to the user group. ' type: array items: type: integer example: - 10 encoding: delete: contentType: application/json add: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' get: operationId: get-user-group-subgroups summary: Get subgroups of a user group tags: - users description: 'Get the subgroups of a [user group](/help/user-groups). **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. New in Zulip 6.0 (feature level 127). ' parameters: - $ref: '#/components/parameters/UserGroupId' - name: direct_subgroup_only in: query description: 'Whether to consider only direct subgroups of the user group or subgroups of subgroups also. ' schema: type: boolean default: false example: true required: false responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} subgroups: type: array items: type: integer description: 'A list containing the IDs of subgroups of the user group. ' example: msg: '' result: success subgroups: - 2 - 3 /user_groups/{user_group_id}/members/{user_id}: get: operationId: get-is-user-group-member summary: Get user group membership status tags: - users description: 'Check whether a user is member of user group. **Changes**: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint. Prior to Zulip 12.0 (feature level 458), this endpoint did not support querying group membership of bot users. Prior to Zulip 10.0 (feature level 303), this would return true when passed a deactivated user who was a member of the user group before being deactivated. New in Zulip 6.0 (feature level 127). ' parameters: - $ref: '#/components/parameters/UserGroupId' - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/DirectMemberOnly' responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} is_user_group_member: type: boolean description: 'Whether the user is member of user group. ' example: msg: '' result: success is_user_group_member: false /user_groups/{user_group_id}/deactivate: post: operationId: deactivate-user-group summary: Deactivate a user group tags: - users description: 'Deactivate a user group. Deactivated user groups cannot be used for mentions, permissions, or any other purpose, but can be reactivated or renamed. Deactivating user groups is preferable to deleting them from the database, since the deactivation model allows audit logs of changes to sensitive group-valued permissions to be maintained. **Changes**: New in Zulip 10.0 (feature level 290). ' parameters: - $ref: '#/components/parameters/UserGroupId' responses: '200': $ref: '#/components/responses/SimpleSuccess' '400': description: Bad request. content: application/json: schema: oneOf: - allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Invalid user group result: error description: 'An example JSON response when the user group ID is invalid. ' - allOf: - $ref: '#/components/schemas/CodedError' - example: code: CANNOT_DEACTIVATE_GROUP_IN_USE msg: Cannot deactivate user group in use. objections: - type: realm settings: - can_create_public_channel_group result: error description: 'An example JSON response when the user group being deactivated is used for a setting or as a subgroup. **Changes**: New in Zulip 10.0 (feature level 298). Previously, this error returned the `"BAD_REQUEST"` code. ' /bots/{bot_id}/api_key: get: operationId: get-bot-api-key summary: Get a bot's API key tags: - users description: 'Fetch the API key for a bot user. Only the bot''s owner and organization administrators have access to a bot''s API key. **Changes**: New in Zulip 12.0 (feature level 463). ' parameters: - $ref: '#/components/parameters/BotId' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} api_key: type: string description: 'The API key for the bot. ' example: msg: '' result: success api_key: hkA04ZYcqXKalvYMA8OeXSfzUOLrtbZv '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: No such bot result: error description: 'An example JSON response when the bot ID is invalid: ' /bots/{bot_id}/api_key/regenerate: post: operationId: regenerate-bot-api-key summary: Regenerate a bot's API key tags: - users description: 'Generate a new API key for a bot user. Only the bot''s owner and organization administrators have access to a bot''s API key. ' parameters: - $ref: '#/components/parameters/BotId' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} api_key: type: string description: 'The new API key for the bot. ' example: msg: '' result: success api_key: hkA04ZYcqXKalvYMA8OeXSfzUOLrtbZv '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: No such bot result: error description: 'An example JSON response when the bot ID is invalid: ' components: schemas: IgnoredParametersSuccess: allOf: - $ref: '#/components/schemas/IgnoredParametersBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} description: '**Changes**: The [`ignored_parameters_unsupported`][ignored_params] array was added as a possible return value for all REST API endpoint JSON success responses in Zulip 7.0 (feature level 167). Previously, it was added to [`POST /users/me/subscriptions/properties`](/api/update-subscription-settings) in Zulip 5.0 (feature level 111) and to [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults) in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0 (feature level 78) as a return value for the [`PATCH /settings`](/api/update-settings) endpoint. A typical successful JSON response with ignored parameters may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters ' example: ignored_parameters_unsupported: - invalid_param_1 - invalid_param_2 msg: '' result: success IgnoredParametersUnsupported: type: array items: type: string description: 'An array of any parameters sent in the request that are not supported by the endpoint. See [error handling](/api/rest-error-handling#ignored-parameters) documentation for details on this and its change history. ' CodedError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false properties: result: {} msg: {} code: {} UserStatus: type: object additionalProperties: false properties: away: type: boolean deprecated: true description: 'If present, the user has marked themself "away". **Changes**: Deprecated in Zulip 6.0 (feature level 148); starting with that feature level, `away` is a legacy way to access the user''s `presence_enabled` setting, with `away = !presence_enabled`. To be removed in a future release. ' status_text: type: string description: 'If present, the text content of the user''s status message. ' emoji_name: type: string description: 'If present, the name for the emoji to associate with the user''s status. **Changes**: New in Zulip 5.0 (feature level 86). ' emoji_code: type: string description: 'If present, a unique identifier, defining the specific emoji codepoint requested, within the namespace of the `reaction_type`. **Changes**: New in Zulip 5.0 (feature level 86). ' reaction_type: type: string enum: - unicode_emoji - realm_emoji - zulip_extra_emoji description: "If present, a string indicating the type of emoji. Each emoji\n`reaction_type` has an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n" JsonSuccess: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} example: msg: '' result: success Attachment: 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. **Changes**: Before Zulip 12.0 (feature level 443), this value was milliseconds since the epoch, not seconds. Changed in Zulip 3.0 (feature level 22). This field was previously a floating point number. ' message_ids: type: array description: 'Array containing the IDs of messages that reference 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. **Changes**: In Zulip 12.0 (feature level 472), this replaced the previous `messages` field, which was an array of objects containing both `id` and `date_sent` properties. ' items: type: integer JsonSuccessBase: description: '**Changes**: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an [`ignored_parameters_unsupported`][ignored_params] array. A typical successful JSON response may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters ' allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: '#/components/schemas/IgnoredParametersUnsupported' GroupSettingValueUpdate: type: object additionalProperties: false properties: new: allOf: - description: 'The new [group-setting value](/api/group-setting-values) for who would have this permission. ' - $ref: '#/components/schemas/GroupSettingValue' old: allOf: - description: 'The expected current [group-setting value](/api/group-setting-values) for who has this permission. ' - $ref: '#/components/schemas/GroupSettingValue' required: - new IgnoredParametersBase: allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: '#/components/schemas/IgnoredParametersUnsupported' JsonResponseBase: type: object properties: result: type: string User: allOf: - $ref: '#/components/schemas/UserBase' - additionalProperties: false properties: user_id: {} delivery_email: nullable: true email: {} full_name: {} date_joined: {} is_active: {} is_owner: {} is_admin: {} is_guest: {} is_bot: {} bot_type: nullable: true bot_owner_id: nullable: true role: {} timezone: {} avatar_url: nullable: true avatar_version: {} is_imported_stub: {} is_deleted: {} profile_data: $ref: '#/components/schemas/ProfileData' CodedErrorBase: allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg - code properties: result: enum: - error msg: type: string code: type: string description: 'A string that identifies the error. ' GroupSettingValue: oneOf: - type: integer description: 'The ID of the [user group](/help/user-groups) with this permission. ' - type: object additionalProperties: false properties: direct_members: description: 'The list of IDs of individual users in the collection of users with this permission. **Changes**: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated. ' type: array items: type: integer direct_subgroups: description: 'The list of IDs of the groups in the collection of users with this permission. ' type: array items: type: integer description: 'An object with these fields: ' ProfileData: type: object description: 'Only present if `is_bot` is false; bots can''t have custom profile fields. A dictionary containing custom profile field data for the user. Each entry maps the integer ID of a custom profile field in the organization to a dictionary containing the user''s data for that field. Generally the data includes just a single `value` key; for those custom profile fields supporting Markdown, a `rendered_value` key will also be present. ' additionalProperties: type: object additionalProperties: false description: '`{id}`: Object with data about what value the user filled in the custom profile field with that ID. ' properties: value: type: string description: 'User''s personal value for this custom profile field. ' rendered_value: type: string description: 'The `value` rendered in HTML. Will only be present for custom profile field types that support Markdown rendering. This user-generated HTML content should be rendered using the same CSS and client-side security protections as are used for message content. See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format. ' ProfileDataUpdate: type: object additionalProperties: false properties: id: type: integer description: 'The ID of the custom profile field to update. ' value: description: 'The new value for the user of the specified custom profile field. If null, then any value already set for the specified custom profile field will be removed. ' oneOf: - type: string nullable: true description: 'A string value that matches the [type of the custom profile field](/help/custom-profile-fields#profile-field-types), e.g., if the profile field type is a link then the string must be a URL. ' - type: array items: type: integer description: 'An array of integer user IDs, which is for the **Users** type of [custom profile field](/help/custom-profile-fields#profile-field-types). ' required: - id - value ModernPresenceFormat: type: object description: '`{user_id}`: Presence data (modern format) for the user with the specified ID. ' additionalProperties: false properties: active_timestamp: type: integer description: 'The UNIX timestamp of the last time a client connected to Zulip reported that the user was actually present (e.g. via focusing a browser window or interacting with a computer running the desktop app). Clients should display users with a current `active_timestamp` as fully present. ' idle_timestamp: type: integer description: 'The UNIX timestamp of the last time the user had a client connected to Zulip, including idle clients where the user hasn''t interacted with the system recently. The Zulip server has no way of distinguishing whether an idle web app user is at their computer, but hasn''t interacted with the Zulip tab recently, or simply left their desktop computer on when they left. Thus, clients should display users with a current `idle_timestamp` but no current `active_timestamp` as potentially present. ' UserBase: type: object description: 'A dictionary containing basic data on a given Zulip user. **Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was replaced by the `can_manage_billing_group` realm setting. ' properties: user_id: type: integer description: 'The unique ID of the user. ' delivery_email: type: string nullable: true description: 'The user''s real email address. This value will be `null` if you cannot access user''s real email address. For bot users, this field is always set to the real email of the bot, because bot users always have `email_address_visibility` set to everyone. **Changes**: Prior to Zulip 7.0 (feature level 163), this field was present only when `email_address_visibility` was restricted and you had access to the user''s real email. As of this feature level, this field is always present, including the case when `email_address_visibility` is set to everyone (and therefore not restricted). ' email: type: string description: 'The Zulip API email address of the user or bot. If you do not have permission to view the email address of the target user, this will be a fake email address that is usable for the Zulip API but nothing else. ' full_name: type: string description: 'Full name of the user or bot, used for all display purposes. ' date_joined: type: string description: 'The time when the user joined. For users imported from other applications and users created via the API, this is set to the account creation time until the user logs in for the first time, after which it is updated to that login time. For imported users, clients can use the `is_imported_stub` flag to determine how to display this field: when `is_imported_stub` is `true`, the user has not yet logged in and this value is the account creation time during import; when `is_imported_stub` is `false`, this value reflects when the user first logged in. **Changes**: Starting with Zulip 12.0 (feature level 475), this field is updated when an imported stub user or a user created via the API logs in for the first time. ' is_active: type: boolean description: 'A boolean specifying whether the user account has been deactivated. ' is_owner: type: boolean description: 'A boolean specifying whether the user is an organization owner. If true, `is_admin` will also be true. **Changes**: New in Zulip 3.0 (feature level 8). ' is_admin: type: boolean description: 'A boolean specifying whether the user is an organization administrator. ' is_guest: type: boolean description: 'A boolean specifying whether the user is a guest user. ' is_bot: type: boolean description: 'A boolean specifying whether the user is a bot or full account. ' bot_type: type: integer nullable: true description: 'An integer describing the type of bot: - `null` if the user isn''t a bot. - `1` for a `Generic` bot. - `2` for an `Incoming webhook` bot. - `3` for an `Outgoing webhook` bot. - `4` for an `Embedded` bot. ' bot_owner_id: type: integer nullable: true description: 'If the user is a bot (i.e. `is_bot` is true), then `bot_owner_id` is the user ID of the bot''s owner (usually, whoever created the bot). Will be `null` for legacy bots that do not have an owner. **Changes**: New in Zulip 3.0 (feature level 1). In previous versions, there was a `bot_owner` field containing the email address of the bot''s owner. ' role: type: integer enum: - 100 - 200 - 300 - 400 - 600 description: '[Organization-level role](/api/roles-and-permissions) of the user. Possible values are: - 100 = Organization owner - 200 = Organization administrator - 300 = Organization moderator - 400 = Member - 600 = Guest **Changes**: New in Zulip 4.0 (feature level 59). ' timezone: type: string description: 'The IANA identifier of the user''s [profile time zone](/help/change-your-timezone), which is used primarily to display the user''s local time to other users. ' avatar_url: type: string nullable: true description: 'URL for the user''s avatar. Will be `null` if the `client_gravatar` query parameter was set to `true`, the current user has access to this user''s real email address, and this user''s avatar is hosted by the Gravatar provider (i.e. this user has never uploaded an avatar). **Changes**: Before Zulip 7.0 (feature level 163), access to a user''s real email address was a realm-level setting. As of this feature level, `email_address_visibility` is a user setting. In Zulip 3.0 (feature level 18), if the client has the `user_avatar_url_field_optional` capability, this will be missing at the server''s sole discretion. ' avatar_version: type: integer description: 'Version for the user''s avatar. Used for cache-busting requests for the user''s avatar. Clients generally shouldn''t need to use this; most avatar URLs sent by Zulip will already end with `?v={avatar_version}`. ' is_imported_stub: type: boolean description: 'Indicates whether this user object is a stub account imported from another chat system. Stub accounts are used to represent the senders for imported messages. Stub accounts can be converted to regular Zulip accounts when the user starts using Zulip, preserving that imported user''s message history. **Changes**: New in Zulip 12.0 (feature level 433). ' example: false is_deleted: type: boolean description: 'A boolean specifying whether the user has been permanently deleted. Deleted users are a subset of deactivated users (`is_active=false`) who have had their account data removed. This field is only present when `true`. **Changes**: New in Zulip 12.0 (feature level 490). ' LegacyPresenceFormat: type: object description: '`{client_name}` or `"aggregated"`: Object containing the details of the user''s presence. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always contain two keys, `"website"` and `"aggregated"`, with identical data. The server no longer stores which client submitted presence updates. Previously, the `{client_name}` keys for these objects were the names of the different clients where the user was logged in, for example `website` or `ZulipDesktop`. ' additionalProperties: false properties: client: type: string description: 'The client''s platform name. **Changes**: Starting with Zulip 7.0 (feature level 178), this will always be `"website"` as the server no longer stores which client submitted presence data. ' status: type: string enum: - idle - active description: 'The status of the user on this client. Will be either `"idle"` or `"active"`. ' timestamp: type: integer description: 'The UNIX timestamp of when this client sent the user''s presence to the server with the precision of a second. ' pushable: type: boolean description: 'Whether the client is capable of showing mobile/push notifications to the user. Not present in objects with the `"aggregated"` key. **Changes**: Starting with Zulip 7.0 (feature level 178), always `false` when present as the server no longer stores which client submitted presence data. ' parameters: DirectMemberOnly: name: direct_member_only in: query description: 'Whether to consider only the direct members of user group and not members of its subgroups. Default is `false`. ' schema: type: boolean example: false required: false UserGroupId: name: user_group_id in: path description: 'The ID of the target user group. ' schema: type: integer example: 38 required: true MutedUserId: name: muted_user_id in: path description: 'The ID of the user to mute/unmute. **Changes**: Before Zulip 8.0 (feature level 188), bot users could not be muted/unmuted, and specifying a bot user''s ID returned an error response. ' schema: type: integer example: 10 required: true IncludeCustomProfileFields: name: include_custom_profile_fields in: query description: 'Whether the client wants [custom profile field](/help/custom-profile-fields) data to be included in the response. **Changes**: New in Zulip 2.1.0. Previous versions do not offer these data via the API. ' schema: type: boolean default: false example: true UserId: name: user_id in: path description: 'The target user''s ID. ' schema: type: integer example: 12 required: true BotId: name: bot_id in: path description: 'The user ID of the target bot. ' schema: type: integer example: 17 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. **Changes**: The default value of this parameter was `false` prior to Zulip 5.0 (feature level 92). ' schema: type: boolean default: true example: false responses: SuccessIgnoredParameters: description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/IgnoredParametersSuccess' SimpleSuccess: description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess' requestBodies: UpdateUser: required: false content: application/x-www-form-urlencoded: schema: type: object properties: full_name: description: 'The user''s full name. **Changes**: Removed unnecessary JSON-encoding of this parameter in Zulip 5.0 (feature level 106). ' type: string example: NewName role: description: 'New [role](/api/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). ' type: integer example: 400 profile_data: description: 'An array of objects describing updates to the [custom profile field](/help/custom-profile-fields) data for the user. ' type: array items: $ref: '#/components/schemas/ProfileDataUpdate' example: - id: 4 value: '0' - id: 5 value: '1909-04-05' new_email: description: 'New email address for the user. Requires the user making the request to be an organization owner and additionally have the `.can_change_user_emails` special permission. **Changes**: New in Zulip 10.0 (feature level 285). ' type: string example: username@example.com encoding: role: contentType: application/json profile_data: contentType: application/json 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. '