openapi: 3.0.1 info: version: 1.0.0 title: Zulip REST authentication server_and_organizations API description: 'Powerful open source group chat ' contact: url: https://zulip.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://{subdomain}.zulipchat.com/api/v1 variables: subdomain: default: example - url: '{server}/api/v1' variables: server: default: https:// - url: https://chat.zulip.org/api/v1 - url: http://localhost:9991/api/v1 - url: http://{subdomain}.testserver/json security: - basicAuth: [] tags: - name: server_and_organizations paths: /realm/emoji/{emoji_name}: post: operationId: upload-custom-emoji summary: Upload custom emoji tags: - server_and_organizations description: 'This endpoint is used to upload a custom emoji for use in the user''s organization. Access to this endpoint depends on the [organization''s configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji). ' x-parameter-description: 'As described above, the image file to upload must be provided in the request''s body. ## Maximum file size The maximum file size for uploads can be configured by the administrator of the Zulip server by setting `MAX_EMOJI_FILE_SIZE_MIB` in the [server''s settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults to 5MB. [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings ' parameters: - name: emoji_name required: true in: path description: 'The name that should be associated with the uploaded emoji image/gif. The emoji name can only contain letters, numbers, dashes, and spaces. Upper and lower case letters are treated the same, and underscores (\_) are treated the same as spaces (consistent with how the Zulip UI handles emoji). ' schema: type: string example: smile requestBody: content: multipart/form-data: schema: type: object properties: filename: type: string format: binary example: /path/to/img.png responses: '200': $ref: '#/components/responses/SimpleSuccess' delete: operationId: deactivate-custom-emoji summary: Deactivate custom emoji tags: - server_and_organizations description: '[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from the user''s organization. Users can only deactivate custom emoji that they added themselves except for organization administrators, who can deactivate any custom emoji. Note that deactivated emoji will still be visible in old messages, reactions, user statuses and channel descriptions. **Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an HTTP status code of 400 when the emoji did not exist, instead of 404. ' parameters: - name: emoji_name required: true in: path description: 'The name of the custom emoji to deactivate. ' schema: type: string example: green_tick responses: '200': $ref: '#/components/responses/SimpleSuccess' '404': description: Not Found. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - description: 'An example JSON response for when no emoji exists with the provided name: ' example: code: BAD_REQUEST result: error msg: Emoji 'green_tick' does not exist /realm/emoji: get: operationId: get-custom-emoji summary: Get all custom emoji tags: - server_and_organizations description: 'Get all the custom emoji in the user''s organization. ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} emoji: type: object description: 'An object in which keys are RealmEmoji ids, and the values describe the custom emoji for that id. ' additionalProperties: $ref: '#/components/schemas/RealmEmoji' example: result: success msg: '' emoji: '1': id: '1' name: green_tick source_url: /user_avatars/1/emoji/images/1.png deactivated: false author_id: 5 /realm/presence: get: operationId: get-presence summary: Get presence of all users tags: - server_and_organizations description: 'Get the presence information of all the users in an organization. If the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level setting is set to `true`, presence information of only accessible users are returned. Complete Zulip apps are recommended to fetch presence information when they post their own state using the [`POST /presence`](/api/update-presence) API endpoint. ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} server_timestamp: type: number description: 'The time when the server fetched the `presences` data included in the response. ' presences: type: object description: 'A dictionary where each entry describes the presence details of a user in the Zulip organization. ' additionalProperties: type: object description: '`{user_email}`: Object containing the details of a user''s presence. The object''s key is the user''s Zulip API email. ' additionalProperties: $ref: '#/components/schemas/LegacyPresenceFormat' example: msg: '' presences: iago@zulip.com: website: client: website pushable: false status: active timestamp: 1656958485 aggregated: client: website status: active timestamp: 1656958485 result: success server_timestamp: 1656958539.6287155 /realm/domains: get: operationId: get-realm-domains summary: Get allowed domains tags: - server_and_organizations description: 'Get the set of allowed domains configured in the organization for user account email addresses. As each Zulip user account is associated with an email address, organization owners can [restrict new account creation (and email changes)](/help/restrict-account-creation) to email addresses with these domains. ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} domains: type: array description: 'A list of objects containing details of each domain allowed for user account email addresses. ' items: $ref: '#/components/schemas/RealmDomain' example: result: success msg: '' domains: - domain: example.com allow_subdomains: false post: operationId: add-realm-domain summary: Add an allowed domain tags: - server_and_organizations description: 'Add a domain to the set of allowed domains configured in the organization for [user account email addresses](/help/restrict-account-creation). **Changes**: Prior to Zulip 6.0 (feature level 143), organization administrators who were not owners could access this endpoint. ' x-requires-owner: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: domain: description: 'The new domain. **Changes**: In Zulip 4.0 (feature level 63), the unnecessary JSON-encoding of this parameter was removed. ' type: string example: example.com allow_subdomains: description: 'Whether subdomains are allowed for this domain. ' type: boolean example: false required: - domain - allow_subdomains responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} new_domain: type: array description: 'An array containing the ID of the newly added domain and the submitted domain name string. ' items: oneOf: - type: integer - type: string example: result: success msg: '' new_domain: - 1 - example.com /realm/domains/{domain}: patch: operationId: patch-realm-domain summary: Update an allowed domain tags: - server_and_organizations description: 'Update whether subdomains are allowed in [user account email addresses](/help/restrict-account-creation) for the specified domain. **Changes**: Prior to Zulip 6.0 (feature level 143), organization administrators who were not owners could access this endpoint. ' x-requires-owner: true parameters: - name: domain in: path description: 'The domain to update. ' schema: type: string example: example.com required: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: allow_subdomains: description: 'Whether subdomains are allowed for this domain. ' type: boolean example: true required: - allow_subdomains responses: '200': $ref: '#/components/responses/SimpleSuccess' delete: operationId: delete-realm-domain summary: Remove an allowed domain tags: - server_and_organizations description: 'Remove the specified domain from the set of allowed domains configured in the organization for [user account email addresses](/help/restrict-account-creation). **Changes**: Prior to Zulip 6.0 (feature level 143), organization administrators who were not owners could access this endpoint. ' x-requires-owner: true parameters: - name: domain in: path description: 'The domain to remove. ' schema: type: string example: example.com required: true responses: '200': $ref: '#/components/responses/SimpleSuccess' /realm/profile_fields: get: operationId: get-custom-profile-fields summary: Get all custom profile fields tags: - server_and_organizations description: 'Get all the [custom profile fields](/help/custom-profile-fields) configured for the user''s organization. ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} custom_fields: type: array description: 'An array containing all the custom profile fields defined in this Zulip organization. ' items: $ref: '#/components/schemas/CustomProfileField' example: result: success msg: '' custom_fields: - id: 1 name: Phone number type: 1 hint: '' field_data: '' order: 1 required: true editable_by_user: false - id: 2 name: Biography type: 2 hint: What are you known for? field_data: '' order: 2 required: true editable_by_user: true - id: 3 name: Favorite food type: 1 hint: Or drink, if you'd prefer field_data: '' order: 3 required: false editable_by_user: true - id: 4 name: Favorite editor type: 3 hint: '' field_data: '{"0":{"text":"Vim","order":"1"},"1":{"text":"Emacs","order":"2"}}' order: 4 display_in_profile_summary: true required: true editable_by_user: true - id: 5 name: Birthday type: 4 hint: '' field_data: '' order: 5 required: false editable_by_user: false - id: 6 name: Favorite website type: 5 hint: Or your personal blog's URL field_data: '' order: 6 display_in_profile_summary: true required: false editable_by_user: true - id: 7 name: Mentor type: 6 hint: '' field_data: '' order: 7 required: true editable_by_user: false - id: 8 name: GitHub type: 7 hint: Enter your GitHub username field_data: '{"subtype":"github"}' order: 8 required: true editable_by_user: true use_for_user_matching: true - id: 9 name: Pronouns type: 8 hint: What pronouns should people use to refer to you? order: 9 required: false editable_by_user: true patch: operationId: reorder-custom-profile-fields summary: Reorder custom profile fields tags: - server_and_organizations description: 'Reorder the custom profile fields in the user''s organization. Custom profile fields are displayed in Zulip UI widgets in order; this endpoint allows administrative settings UI to change the field ordering. This endpoint is used to implement the dragging feature described in the [custom profile fields documentation](/help/custom-profile-fields). ' x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: order: description: 'A list of the IDs of all the custom profile fields defined in this organization, in the desired new order. ' type: array items: type: integer example: - 11 - 10 - 9 - 8 - 7 - 6 - 5 - 4 - 3 - 2 - 1 required: - order encoding: order: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' post: operationId: create-custom-profile-field summary: Create a custom profile field tags: - server_and_organizations description: '[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user''s organization. ' x-requires-administrator: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: description: 'The name of the custom profile field, which will appear both in user-facing settings UI for configuring custom profile fields and in UI displaying a user''s profile. ' type: string example: Favorite programming language hint: description: 'The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields. ' type: string example: Your favorite programming language. field_type: description: 'The field type can be any of the supported custom profile field types. See the [custom profile fields documentation](/help/custom-profile-fields) for more details on what each type means. - **1**: Short text - **2**: Paragraph - **3**: Dropdown - **4**: Date - **5**: Link - **6**: Users - **7**: External account - **8**: Pronouns **Changes**: Field type `8` added in Zulip 6.0 (feature level 151). ' type: integer example: 3 field_data: description: 'Field types 3 (Dropdown) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (Dropdown), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option. The interface for field type 7 is not yet stabilized. ' type: object example: python: text: Python order: '1' java: text: Java order: '2' display_in_profile_summary: description: 'Whether clients should display this profile field in a summary section of a user''s profile (or in a more easily accessible "small profile"). At most 2 profile fields may have this property be true in a given organization. The "Users" profile field is not supported, but that is likely to be temporary. [profile-field-types]: /help/custom-profile-fields#profile-field-types **Changes**: Before Zulip 12.0 (feature level 476), the "Paragraph" field type was not supported. New in Zulip 6.0 (feature level 146). ' type: boolean example: true required: description: 'Whether an organization administrator has configured this profile field as required. Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field. **Changes**: New in Zulip 9.0 (feature level 244). ' type: boolean example: true editable_by_user: description: 'Whether regular users can edit this profile field on their own account. Note that organization administrators can edit custom profile fields for any user regardless of this setting. **Changes**: New in Zulip 10.0 (feature level 296). ' type: boolean example: true use_for_user_matching: description: 'Whether this custom profile field should be used to match users in typeahead suggestions. Only allowed for Short Text and External Account [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: New in Zulip 12.0 (feature level 455). ' type: boolean example: false required: - field_type encoding: field_type: contentType: application/json field_data: contentType: application/json display_in_profile_summary: contentType: application/json required: contentType: application/json editable_by_user: contentType: application/json use_for_user_matching: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: 'The ID for the custom profile field. ' example: result: success msg: '' id: 9 /realm/user_settings_defaults: patch: operationId: update-realm-user-settings-defaults summary: Update realm-level defaults of user settings tags: - server_and_organizations x-requires-administrator: true description: 'Change the [default values of settings][new-user-defaults] for new users joining the organization. Essentially all [personal preference settings](/api/update-settings) are supported. This feature can be invaluable for customizing Zulip''s default settings for notifications or UI to be appropriate for how the organization is using Zulip. (Note that this only supports personal preference settings, like when to send push notifications or what emoji set to use, not profile or identity settings that naturally should be different for each user). Note that this endpoint cannot, at present, be used to modify settings for existing users in any way. **Changes**: 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. New in Zulip 5.0 (feature level 96). If any parameters sent in the request are not supported by this endpoint, an [`ignored_parameters_unsupported`][ignored-parameters] array will be returned in the JSON success response. [new-user-defaults]: /help/configure-default-new-user-settings [ignored-parameters]: /api/rest-error-handling#ignored-parameters ' x-curl-examples-parameters: oneOf: - type: include parameters: enum: - left_side_userlist - emojiset requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: starred_message_counts: description: 'Whether clients should display the [number of starred messages](/help/star-a-message#display-the-number-of-starred-messages). ' type: boolean example: true receives_typing_notifications: description: 'Whether the user is configured to receive typing notifications from other users. The server will only deliver typing notifications events to users who for whom this is enabled. **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were only options to disable sending typing notifications. ' type: boolean example: true web_suggest_update_timezone: 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). ' type: boolean example: true fluid_layout_width: description: 'Whether to use the [maximum available screen width](/help/enable-full-width-display) for the web app''s center panel (message feed, recent conversations) on wide screens. ' type: boolean example: true high_contrast_mode: description: 'This setting is reserved for use to control variations in Zulip''s design to help visually impaired users. ' type: boolean example: true web_mark_read_on_scroll_policy: description: 'Whether or not to mark messages as read when the user scrolls through their feed. - 1 - Always - 2 - Only in conversation views - 3 - Never **Changes**: New in Zulip 7.0 (feature level 175). Previously, there was no way for the user to configure this behavior on the web, and the Zulip web and desktop apps behaved like the "Always" setting when marking messages as read. ' type: integer enum: - 1 - 2 - 3 example: 1 web_channel_default_view: description: 'Web/desktop app setting controlling the default navigation behavior when clicking on a channel link. - 1 - Top topic in the channel - 2 - Channel feed - 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 - 3 - 4 example: 1 web_font_size_px: description: 'User-configured primary `font-size` for the web application, in pixels. **Changes**: New in Zulip 9.0 (feature level 245). Previously, font size was only adjustable via browser zoom. Note that this setting was not fully implemented at this feature level. ' type: integer example: 14 web_line_height_percent: description: 'User-configured primary `line-height` for the web application, in percent, so a value of 120 represents a `line-height` of 1.2. **Changes**: New in Zulip 9.0 (feature level 245). Previously, line height was not user-configurable. Note that this setting was not fully implemented at this feature level. ' type: integer example: 122 color_scheme: description: 'Controls which [color theme](/help/dark-theme) to use. - 1 - Automatic - 2 - Dark theme - 3 - Light theme Automatic detection is implementing using the standard `prefers-color-scheme` media query. ' type: integer enum: - 1 - 2 - 3 example: 1 enable_drafts_synchronization: description: 'A boolean parameter to control whether synchronizing drafts is enabled for the user. When synchronization is disabled, all drafts stored in the server will be automatically deleted from the server. This does not do anything (like sending events) to delete local copies of drafts stored in clients. ' type: boolean example: true translate_emoticons: description: 'Whether to [translate emoticons to emoji](/help/configure-emoticon-translations) in messages the user sends. ' type: boolean example: true display_emoji_reaction_users: description: 'Whether to display the names of reacting users on a message. When enabled, clients should display the names of reacting users, rather than a count, for messages with few total reactions. The ideal cutoff may depend on the space available for displaying reactions; the official web application displays names when 3 or fewer total reactions are present with this setting enabled. **Changes**: New in Zulip 6.0 (feature level 125). ' type: boolean example: false web_home_view: description: 'The [home view](/help/configure-home-view) used when opening a new Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly. - "recent" - 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). ' type: string example: all_messages web_escape_navigates_to_home_view: description: 'Whether the escape key navigates to the [configured home view](/help/configure-home-view). **Changes**: New in Zulip 8.0 (feature level 219). Previously, this was called `escape_navigates_to_default_view`, which was new in Zulip 5.0 (feature level 107). ' type: boolean example: true left_side_userlist: description: 'Whether the users list on left sidebar in narrow windows. This feature is not heavily used and is likely to be reworked. ' type: boolean example: true emojiset: description: 'The user''s configured [emoji set](/help/emoji-and-emoticons#use-emoticons), used to display emoji to the user everywhere they appear in the UI. - "google" - Google - "twitter" - Twitter - "text" - Plain text ' 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 ' type: integer enum: - 1 - 2 - 3 example: 1 user_list_style: description: 'The style selected by the user for the right sidebar user list. - 1 - Compact - 2 - With status - 3 - With avatar and status **Changes**: New in Zulip 6.0 (feature level 141). ' type: integer enum: - 1 - 2 - 3 example: 1 web_animate_image_previews: description: 'Controls how animated images should be played in the message feed in the web/desktop application. - "always" - Always play the animated images in the message feed. - "on_hover" - Play the animated images on hover over them in the message feed. - "never" - Never play animated images in the message feed. **Changes**: New in Zulip 9.0 (feature level 275). Previously, animated images always used to play in the message feed by default. This setting controls this behaviour. ' type: string enum: - always - on_hover - never example: on_hover web_stream_unreads_count_display_policy: description: 'Configuration for which channels should be displayed with a numeric unread count in the left sidebar. Channels that do not have an unread count will have a simple dot indicator for whether there are any unread messages. - 1 - All channels - 2 - Unmuted channels and topics - 3 - No channels **Changes**: New in Zulip 8.0 (feature level 210). ' type: integer enum: - 1 - 2 - 3 example: 2 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). ' example: true 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 enable_stream_desktop_notifications: description: 'Enable visual desktop notifications for channel messages. ' type: boolean example: true enable_stream_email_notifications: description: 'Enable email notifications for channel messages. ' type: boolean example: true enable_stream_push_notifications: description: 'Enable mobile notifications for channel messages. ' type: boolean example: true enable_stream_audible_notifications: description: 'Enable audible desktop notifications for channel messages. ' type: boolean example: true notification_sound: description: 'Notification sound name. ' type: string example: ding enable_desktop_notifications: description: 'Enable visual desktop notifications for direct messages and @-mentions. ' type: boolean example: true enable_sounds: description: 'Enable audible desktop notifications for direct messages and @-mentions. ' type: boolean example: true enable_followed_topic_desktop_notifications: description: 'Enable visual desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true enable_followed_topic_email_notifications: description: 'Enable email notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true enable_followed_topic_push_notifications: description: 'Enable push notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: false enable_followed_topic_audible_notifications: description: 'Enable audible desktop notifications for messages sent to followed topics. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: false email_notifications_batching_period_seconds: description: 'The duration (in seconds) for which the server should wait to batch email notifications before sending them. ' type: integer example: 120 enable_offline_email_notifications: description: 'Enable email notifications for direct messages and @-mentions received when the user is offline. ' type: boolean example: true enable_offline_push_notifications: description: 'Enable mobile notification for direct messages and @-mentions received when the user is offline. ' type: boolean example: true enable_online_push_notifications: description: 'Enable mobile notification for direct messages and @-mentions received when the user is online. ' type: boolean example: true enable_digest_emails: description: 'Enable digest emails when the user is away. ' type: boolean example: true message_content_in_email_notifications: description: 'Include the message''s content in email notifications for new messages. ' type: boolean example: true pm_content_in_desktop_notifications: description: 'Include content of direct messages in desktop notifications. ' type: boolean example: true wildcard_mentions_notify: description: 'Whether wildcard mentions (E.g. @**all**) should send notifications like a personal mention. ' type: boolean example: true enable_followed_topic_wildcard_mentions_notify: description: 'Whether wildcard mentions (e.g., @**all**) in messages sent to followed topics should send notifications like a personal mention. **Changes**: New in Zulip 8.0 (feature level 189). ' type: boolean example: true desktop_icon_count_display: description: 'Unread count badge (appears in desktop sidebar and browser tab) - 1 - All unread messages - 2 - DMs, mentions, and followed topics - 3 - DMs and mentions - 4 - None **Changes**: In Zulip 8.0 (feature level 227), added `DMs, mentions, and followed topics` option, renumbering the options to insert it in order. ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 realm_name_in_email_notifications_policy: description: 'Whether to [include organization name in subject of message notification emails](/help/email-notifications#include-organization-name-in-subject-line). - 1 - Automatic - 2 - Always - 3 - Never **Changes**: New in Zulip 7.0 (feature level 168), replacing the previous `realm_name_in_notifications` boolean; `true` corresponded to `Always`, and `false` to `Never`. ' type: integer enum: - 1 - 2 - 3 example: 1 automatically_follow_topics_policy: description: 'Which [topics to follow automatically](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_unmute_topics_in_muted_streams_policy: description: 'Which [topics to unmute automatically in muted channels](/help/mute-a-topic). - 1 - Topics the user participates in - 2 - Topics the user sends a message to - 3 - Topics the user starts - 4 - Never **Changes**: New in Zulip 8.0 (feature level 214). ' type: integer enum: - 1 - 2 - 3 - 4 example: 1 automatically_follow_topics_where_mentioned: description: 'Whether the server will automatically mark the user as following topics where the user is mentioned. **Changes**: New in Zulip 8.0 (feature level 235). ' type: boolean example: true 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. ' type: boolean example: true enter_sends: description: 'Whether pressing Enter in the compose box sends a message (or saves a message edit). ' type: boolean example: true twenty_four_hour_time: description: 'Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). **Changes**: New in Zulip 5.0 (feature level 99). Previously, this default was edited using the `default_twenty_four_hour_time` parameter to the `PATCH /realm` endpoint. ' type: boolean example: true send_private_typing_notifications: description: 'Whether [typing notifications](/help/typing-notifications) be sent when composing direct messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true send_stream_typing_notifications: description: 'Whether [typing notifications](/help/typing-notifications) be sent when composing channel messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true send_read_receipts: description: 'Whether other users are allowed to see whether you''ve read messages. **Changes**: New in Zulip 5.0 (feature level 105). ' type: boolean example: true email_address_visibility: description: 'The [policy][permission-level] for [which other users][help-email-visibility] in this organization can see the user''s real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility ' type: integer enum: - 1 - 2 - 3 - 4 - 5 example: 1 web_navigate_to_sent_message: description: 'Web/desktop app setting for whether the user''s view should automatically go to the conversation where they sent a message. **Changes**: New in Zulip 9.0 (feature level 268). Previously, this behavior was not configurable. ' type: boolean example: true encoding: 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_mark_read_on_scroll_policy: contentType: application/json web_channel_default_view: contentType: application/json web_font_size_px: contentType: application/json web_line_height_percent: contentType: application/json color_scheme: contentType: application/json enable_drafts_synchronization: contentType: application/json translate_emoticons: contentType: application/json display_emoji_reaction_users: contentType: application/json web_escape_navigates_to_home_view: contentType: application/json left_side_userlist: contentType: application/json demote_inactive_streams: contentType: application/json user_list_style: contentType: application/json web_stream_unreads_count_display_policy: contentType: application/json 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 enable_followed_topic_desktop_notifications: contentType: application/json enable_followed_topic_email_notifications: contentType: application/json enable_followed_topic_push_notifications: contentType: application/json enable_followed_topic_audible_notifications: contentType: application/json email_notifications_batching_period_seconds: contentType: application/json enable_offline_email_notifications: contentType: application/json enable_offline_push_notifications: contentType: application/json enable_online_push_notifications: contentType: application/json enable_digest_emails: contentType: application/json message_content_in_email_notifications: contentType: application/json pm_content_in_desktop_notifications: contentType: application/json wildcard_mentions_notify: contentType: application/json enable_followed_topic_wildcard_mentions_notify: contentType: application/json desktop_icon_count_display: contentType: application/json realm_name_in_email_notifications_policy: contentType: application/json automatically_follow_topics_policy: contentType: application/json automatically_unmute_topics_in_muted_streams_policy: contentType: application/json automatically_follow_topics_where_mentioned: contentType: application/json presence_enabled: contentType: application/json enter_sends: contentType: application/json twenty_four_hour_time: contentType: application/json send_private_typing_notifications: contentType: application/json send_stream_typing_notifications: contentType: application/json send_read_receipts: contentType: application/json email_address_visibility: contentType: application/json web_navigate_to_sent_message: contentType: application/json responses: '200': $ref: '#/components/responses/SuccessIgnoredParameters' /realm/linkifiers: get: operationId: get-linkifiers summary: Get linkifiers tags: - server_and_organizations description: 'List all of an organization''s configured [linkifiers](/help/add-a-custom-linkifier), regular expression patterns that are automatically linkified when they appear in messages and topics. **Changes**: New in Zulip 4.0 (feature level 54). On older versions, a similar `GET /realm/filters` endpoint was available with each entry in a `[pattern, url_format, id]` tuple format. ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} linkifiers: type: array description: 'An ordered array of objects, where each object describes a linkifier. Clients should always process linkifiers in the order given; this is important if the realm has linkifiers with overlapping patterns. The order can be modified using [`PATCH /realm/linkifiers`](/api/reorder-linkifiers). ' items: type: object additionalProperties: false properties: pattern: type: string description: 'The string regex pattern which represents the pattern that should be linkified by this linkifier. ' url_template: type: string description: 'The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template to be used for linkifying matches. **Changes**: New in Zulip 7.0 (feature level 176). This replaced `url_format`, which contained a URL format string. ' id: type: integer description: 'The ID of the linkifier. ' example_input: type: string nullable: true description: 'An example input string that matches the linkifier''s pattern. This is required for reverse linkifiers. **Changes**: New in Zulip 12.0 (feature level 471). ' reverse_template: type: string nullable: true description: 'A simple template using `{variable}` for variables that can be used to generate the Markdown linkifier syntax, given a URL matching the URL template. `{{ "{{/}}" }}` can be used for literal `{/}` characters. **Changes**: New in Zulip 12.0 (feature level 471). ' alternative_url_templates: type: array items: type: string description: 'An array of additional [RFC 6570][rfc6570] compliant URL template strings that are used for reverse linkification (converting pasted URLs to linkifier pattern text). These templates have no effect on forward linkification. [rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html **Changes**: New in Zulip 12.0 (feature level e2b257). ' example: msg: '' linkifiers: - pattern: '#(?P[0-9]+)' url_template: https://github.com/zulip/zulip/issues/{id} id: 1 example_input: '#1234' reverse_template: '#{id}' alternative_url_templates: - https://github.com/zulip/zulip/pull/{id} result: success patch: operationId: reorder-linkifiers summary: Reorder linkifiers tags: - server_and_organizations description: 'Change the order that the regular expression patterns in the organization''s [linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics. Useful when defining linkifiers with overlapping patterns. **Changes**: New in Zulip 8.0 (feature level 202). Before this feature level, linkifiers were always processed in order by ID, which meant users would need to delete and recreate them to reorder the list of linkifiers. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: ordered_linkifier_ids: description: 'A list of the IDs of all the linkifiers defined in this organization, in the desired new order. ' type: array items: type: integer example: - 3 - 2 - 1 - 5 required: - ordered_linkifier_ids encoding: ordered_linkifier_ids: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' /realm/filters: post: operationId: add-linkifier summary: Add a linkifier tags: - server_and_organizations description: 'Configure [linkifiers](/help/add-a-custom-linkifier), regular expression patterns that are automatically linkified when they appear in messages and topics. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: pattern: $ref: '#/components/schemas/LinkifierPattern' url_template: $ref: '#/components/schemas/LinkifierURLTemplate' example_input: type: string nullable: true example: '#1234' description: 'An example input string that matches the linkifier''s pattern. This is required for reverse linkifiers. **Changes**: New in Zulip 12.0 (feature level 471). ' reverse_template: type: string nullable: true example: '#{id}' description: 'A simple template using `{variable}` for variables that can be used to generate the Markdown linkifier syntax, given a URL matching the URL template. `{{ "{{/}}" }}` can be used for literal `{/}` characters. Server verifies that variables extracted from example_input using url_pattern when passed to reverse_template returns example_input back to us. **Changes**: New in Zulip 12.0 (feature level 471). ' alternative_url_templates: type: array items: type: string example: - https://github.com/zulip/zulip/pull/{id} description: 'An array of additional [RFC 6570][rfc6570] compliant URL template strings that are used for reverse linkification (converting pasted URLs to linkifier pattern text). These templates have no effect on forward linkification. [rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html **Changes**: New in Zulip 12.0 (feature level e2b257). ' required: - pattern - url_template encoding: alternative_url_templates: contentType: application/json responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: 'The numeric ID assigned to this filter. ' example: id: 42 result: success msg: '' /realm/filters/{filter_id}: delete: operationId: remove-linkifier summary: Remove a linkifier tags: - server_and_organizations description: 'Remove [linkifiers](/help/add-a-custom-linkifier), regular expression patterns that are automatically linkified when they appear in messages and topics. ' parameters: - name: filter_id in: path description: 'The ID of the linkifier that you want to remove. ' schema: type: integer example: 43 required: true responses: '200': $ref: '#/components/responses/SimpleSuccess' patch: operationId: update-linkifier summary: Update a linkifier tags: - server_and_organizations description: 'Update a [linkifier](/help/add-a-custom-linkifier), regular expression patterns that are automatically linkified when they appear in messages and topics. **Changes**: New in Zulip 4.0 (feature level 57). ' parameters: - name: filter_id in: path description: 'The ID of the linkifier that you want to update. ' schema: type: integer example: 5 required: true requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: pattern: $ref: '#/components/schemas/LinkifierPattern' url_template: $ref: '#/components/schemas/LinkifierURLTemplate' example_input: type: string nullable: true example: '#1234' description: 'An example input string that matches the linkifier''s pattern. This is required for reverse linkifiers. Passing an empty string will set this field back to null. **Changes**: New in Zulip 12.0 (feature level 471). ' reverse_template: type: string nullable: true example: '#{id}' description: 'A simple template using `{variable}` for variables that can be used to generate the Markdown linkifier syntax, given a URL matching the URL template. Passing an empty string will set this field back to null. Server verifies that variables extracted from example_input using url_pattern when passed to reverse_template returns example_input back to us. `{{ "{{/}}" }}` can be used for literal `{/}` characters. **Changes**: New in Zulip 12.0 (feature level 471). ' alternative_url_templates: type: array items: type: string example: - https://github.com/zulip/zulip/pull/{id} description: 'An array of additional [RFC 6570][rfc6570] compliant URL template strings that are used for reverse linkification (converting pasted URLs to linkifier pattern text). These templates have no effect on forward linkification. [rfc6570]: https://www.rfc-editor.org/rfc/rfc6570.html **Changes**: New in Zulip 12.0 (feature level e2b257). ' required: - pattern - url_template encoding: alternative_url_templates: contentType: application/json responses: '200': $ref: '#/components/responses/SimpleSuccess' /realm/playgrounds: post: operationId: add-code-playground summary: Add a code playground tags: - server_and_organizations description: 'Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization. **Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was fixed in Zulip 4.0 (feature level 57). ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: description: 'The user-visible display name of the playground which can be used to pick the target playground, especially when multiple playground options exist for that programming language. ' type: string example: Python playground pygments_language: description: 'The name of the Pygments language lexer for that programming language. ' type: string example: Python url_template: description: 'The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template for the playground. The template should contain exactly one variable named `code`, which determines how the extracted code should be substituted in the playground URL. **Changes**: New in Zulip 8.0 (feature level 196). This replaced the `url_prefix` parameter, which was used to construct URLs by just concatenating `url_prefix` and `code`. ' type: string example: https://python.example.com?code={code} required: - name - pygments_language - url_template responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: 'The numeric ID assigned to this playground. ' example: id: 1 result: success msg: '' /realm/playgrounds/{playground_id}: delete: operationId: remove-code-playground summary: Remove a code playground tags: - server_and_organizations description: 'Remove a [code playground](/help/code-blocks#code-playgrounds) previously configured for an organization. **Changes**: New in Zulip 4.0 (feature level 49). ' parameters: - name: playground_id in: path description: 'The ID of the playground that you want to remove. ' schema: type: integer example: 1 required: true responses: '200': $ref: '#/components/responses/SimpleSuccess' /export/realm: get: operationId: get-realm-exports summary: Get all data exports tags: - server_and_organizations x-requires-administrator: true description: 'Fetch all the public and standard [data exports][export-data] of the organization. **Changes**: Prior to Zulip 10.0 (feature level 304), only public data exports could be fetched using this endpoint. New in Zulip 2.1. [export-data]: /help/export-your-organization#export-data-in-an-importable-format ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} exports: type: array description: 'An array of dictionaries where each dictionary contains details about a data export of the organization. ' items: $ref: '#/components/schemas/RealmExport' example: exports: - acting_user_id: 11 deleted_timestamp: null export_type: public export_time: 1722243168.134179 export_url: http://example.zulipchat.com/user_avatars/exports/2/FprbwiF0c_sCN0O-rf-ryFtc/zulip-export-p6yuxc45.tar.gz id: 323 failed_timestamp: null pending: false msg: '' result: success post: operationId: export-realm summary: Create a data export tags: - server_and_organizations x-requires-administrator: true description: "Create a public or a standard [data export][export-data] of the organization.\n\n!!! warn \"\"\n\n **Note**: If you're the administrator of a self-hosted installation,\n you may be looking for the documentation on [server data export and\n import][data-export] or [server backups][backups].\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be created using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-data-in-an-importable-format\n[data-export]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#data-export\n[backups]: https://zulip.readthedocs.io/en/stable/production/export-and-import.html#backups\n" requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: export_type: description: "Whether the data export should be public, full with consent,\nor full without consent.\n\n- `public` = Public data only export.\n- `full_with_consent` = Public and private data export (with consent), which includes\n private data for users who have granted consent.\n- `full_without_consent` = All public and private data export, which includes private data for\n all users. This option requires the organization to have\n the `owner_full_content_access` feature enabled.\n\nIf not specified, defaults to `public`.\n\n**Changes**: Zulip 12.0 (feature level 449) changed the type of\nthis field from int to string with `1` being replaced by `public` and\n`2` being replaced by `full_with_consent`. The option `full_without_consent`\nwas added for full exports without member consent.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nall export requests were public data exports.\n" type: string enum: - public - full_with_consent - full_without_consent default: public example: full_with_consent responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} id: type: integer description: 'The ID of the data export created. **Changes**: New in Zulip 7.0 (feature level 182). ' example: id: 1 result: success msg: '' '400': description: Bad request. content: application/json: schema: allOf: - $ref: '#/components/schemas/CodedError' - example: code: BAD_REQUEST msg: Please request a manual export from zulip-admin@example.com. result: error description: 'An example JSON error response for when the data export exceeds the maximum allowed data export size. ' /export/realm/consents: get: operationId: get-realm-export-consents summary: Get data export consent state tags: - server_and_organizations x-requires-administrator: true description: 'Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data) for their private data to be exported by organization administrators. **Changes**: Changes in Zulip 12.0 (feature level 430). Added an integer field `email_address_visibility` to the objects in the `export_consents` array. New in Zulip 10.0 (feature level 295). ' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} export_consents: type: array description: 'An array of objects where each object contains a user ID, whether the user has consented for their private data to be exported, and their email visibility policy. ' items: type: object additionalProperties: false properties: user_id: description: 'The user ID. ' type: integer consented: description: 'Whether the user has consented for their private data export. ' type: boolean email_address_visibility: $ref: '#/components/schemas/EmailAddressVisibility' example: export_consents: - user_id: 11 consented: true email_address_visibility: 1 - user_id: 6 consented: false email_address_visibility: 2 msg: '' result: success /realm/test_welcome_bot_custom_message: post: operationId: test-welcome-bot-custom-message summary: Test welcome bot custom message tags: - server_and_organizations x-requires-administrator: true description: 'Sends a test Welcome Bot custom message to the acting administrator. This allows administrators to preview how the custom welcome message will appear when received by new users upon joining the organization. **Changes**: New in Zulip 11.0 (feature level 416). ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: welcome_message_custom_text: description: 'Custom message text, in Zulip Markdown format, to be used for this test message. Maximum length is 8000 Unicode code points. ' type: string maxLength: 8000 example: Welcome to Zulip! We're excited to have you on board. required: - welcome_message_custom_text responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} message_id: type: integer description: 'The message_id of the test welcome bot custom message. ' example: result: success msg: '' message_id: 1 /server_settings: get: operationId: get-server-settings summary: Get server settings tags: - server_and_organizations x-response-description: "Please note that not all of these attributes are guaranteed to appear in a\nresponse, for two reasons:\n\n* This endpoint has evolved over time, so responses from older Zulip servers\n might be missing some keys (in which case a client should assume the\n appropriate default).\n* If a `/server_settings` request is made to the root domain of a\n multi-subdomain server, like the root domain of zulip.com, the settings\n that are realm-specific are not known and thus not provided.\n" description: "Fetch global settings for a Zulip server.\n\n**Note:** this endpoint does not require any authentication at all, and you can use it to check:\n\n- If this is a Zulip server, and if so, what version of Zulip it's running.\n- What a Zulip client (e.g. a mobile app or\n [zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to\n know in order to display a login prompt for the server (e.g. what\n authentication methods are available).\n" responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} authentication_methods: type: object additionalProperties: false deprecated: true description: 'Each key-value pair in the object indicates whether the authentication method is enabled on this server. **Changes**: Deprecated in Zulip 2.1.0, in favor of the more expressive `external_authentication_methods`. ' properties: password: description: 'Whether the user can authenticate using password. ' type: boolean dev: description: 'Whether the user can authenticate using development API key. ' type: boolean email: description: 'Whether the user can authenticate using email. ' type: boolean ldap: description: 'Whether the user can authenticate using LDAP. ' type: boolean remoteuser: description: 'Whether the user can authenticate using REMOTE_USER. ' type: boolean github: description: 'Whether the user can authenticate using their GitHub account. ' type: boolean azuread: description: 'Whether the user can authenticate using their Microsoft Entra ID account. ' type: boolean gitlab: description: 'Whether the user can authenticate using their GitLab account. **Changes**: New in Zulip 3.0 (feature level 1). ' type: boolean apple: description: 'Whether the user can authenticate using their Apple account. ' type: boolean google: description: 'Whether the user can authenticate using their Google account. ' type: boolean saml: description: 'Whether the user can authenticate using SAML. ' type: boolean openid connect: description: 'Whether the user can authenticate using OpenID Connect. ' type: boolean discord: description: 'Whether the user can authenticate using their Discord account. **Changes**: New in Zulip 12.0 (feature level 488). ' type: boolean external_authentication_methods: type: array description: 'A list of dictionaries describing the available external authentication methods (E.g. Google, GitHub, or SAML) enabled for this organization. The list is sorted in the order in which these authentication methods should be displayed. **Changes**: New in Zulip 2.1.0. ' items: type: object additionalProperties: false properties: name: type: string description: 'A unique, table, machine-readable name for the authentication method, intended to be used by clients with special behavior for specific authentication methods to correctly identify the method. ' display_name: type: string description: 'Display name of the authentication method, to be used in all buttons for the authentication method. ' display_icon: type: string nullable: true description: 'URL for an image to be displayed as an icon in all buttons for the external authentication method. This URL should be resolved relative to the server''s base URL. When `null`, no icon should be displayed. ' login_url: type: string description: 'URL to be used to initiate authentication using this method. ' signup_url: type: string description: 'URL to be used to initiate account registration using this method. ' zulip_feature_level: type: integer description: 'An integer indicating what features are available on the server. The feature level increases monotonically; a value of N means the server supports all API features introduced before feature level N. This is designed to provide a simple way for client apps to decide whether the server supports a given feature or API change. See the [changelog](/api/changelog) for details on what each feature level means. **Changes**: New in Zulip 3.0 (feature level 1). We recommend using an implied value of 0 for Zulip servers that do not send this field. ' zulip_version: type: string description: 'The server''s version number. This is often a release version number, like `2.1.7`. But for a server running a [version from Git][git-release], it will be a Git reference to the commit, like `5.0-dev-1650-gc3fd37755f`. [git-release]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#git-versions ' zulip_merge_base: type: string description: 'The `git merge-base` between `zulip_version` and official branches in the public [Zulip server and web app repository](https://github.com/zulip/zulip), in the same format as `zulip_version`. This will equal `zulip_version` if the server is not running a fork of the Zulip server. This will be `""` if unavailable. **Changes**: New in Zulip 5.0 (feature level 88). ' push_notifications_enabled: type: boolean description: 'Whether mobile/push notifications are configured. ' is_incompatible: type: boolean description: 'Whether the Zulip client that has sent a request to this endpoint is deemed incompatible with the server. ' email_auth_enabled: type: boolean description: 'Setting for allowing users authenticate with an email-password combination. ' require_email_format_usernames: type: boolean description: 'Whether all valid usernames for authentication to this organization will be email addresses. This is important for clients to know whether to do client side validation of email address format in a login prompt. This value will be false if the server has [LDAP authentication][ldap-auth] enabled with a username and password combination. [ldap-auth]: https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory ' realm_uri: type: string deprecated: true description: 'The organization''s canonical URL. Alias of `realm_url`. **Changes**: Deprecated in Zulip 9.0 (feature level 257). The term "URI" is deprecated in [web standards](https://url.spec.whatwg.org/#goals). ' realm_url: type: string description: 'The organization''s canonical URL. **Changes**: New in Zulip 9.0 (feature level 257), replacing the deprecated `realm_uri`. ' realm_name: type: string description: 'The organization''s name (for display purposes). ' realm_icon: type: string description: 'The URL for the organization''s logo formatted as a square image, used for identifying the organization in small locations in the mobile and desktop apps. ' realm_description: type: string description: 'HTML description of the organization, as configured by the [organization profile](/help/create-your-organization-profile). ' realm_web_public_access_enabled: type: boolean description: 'Whether the organization has enabled the creation of [web-public channels](/help/public-access-option) and at least one web-public channel on the server currently exists. Clients that support viewing content in web-public channels without an account can use this to determine whether to offer that feature on the login page for an organization. **Changes**: New in Zulip 5.0 (feature level 116). ' example: authentication_methods: password: true dev: true email: true ldap: false remoteuser: false github: true azuread: false google: true saml: true zulip_version: 5.0-dev-1650-gc3fd37755f zulip_merge_base: 5.0-dev-1646-gea6b21cd8c push_notifications_enabled: false msg: '' is_incompatible: false email_auth_enabled: true require_email_format_usernames: true realm_uri: http://localhost:9991 realm_url: http://localhost:9991 realm_name: Zulip Dev realm_icon: https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon realm_description:

The Zulip development environment default organization. It's great for testing!

realm_web_public_access_enabled: false result: success external_authentication_methods: - name: saml:idp_name display_name: SAML display_icon: null login_url: /accounts/login/social/saml/idp_name signup_url: /accounts/register/social/saml/idp_name - name: google display_name: Google display_icon: /static/images/authentication_backends/googl_e-icon.png login_url: /accounts/login/social/google signup_url: /accounts/register/social/google - name: github display_name: GitHub display_icon: /static/images/authentication_backends/github-icon.png login_url: /accounts/login/social/github signup_url: /accounts/register/social/github components: schemas: 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' CustomProfileField: type: object additionalProperties: false description: 'Dictionary containing the details of a custom profile field configured for this organization. ' properties: id: type: integer description: 'The ID of the custom profile field. This will be referenced in the custom profile fields section of user objects. ' type: type: integer description: 'An integer indicating the type of the custom profile field, which determines how it is configured and displayed to users. See the [Custom profile fields](/help/custom-profile-fields#profile-field-types) article for details on what each type means. - **1**: Short text - **2**: Paragraph - **3**: Dropdown - **4**: Date - **5**: Link - **6**: Users - **7**: External account - **8**: Pronouns **Changes**: Field type `8` added in Zulip 6.0 (feature level 151). ' order: type: integer description: 'Custom profile fields are displayed in both settings UI and UI showing users'' profiles in increasing `order`. ' name: type: string description: 'The name of the custom profile field. ' hint: type: string description: 'The help text to be displayed for the custom profile field in user-facing settings UI for configuring custom profile fields. ' field_data: type: string description: 'Field types 3 (Dropdown) and 7 (External account) support storing additional configuration for the field type in the `field_data` attribute. For field type 3 (Dropdown), this attribute is a JSON dictionary defining the choices and the order they will be displayed in the dropdown UI for individual users to select an option. The interface for field type 7 is not yet stabilized. ' display_in_profile_summary: type: boolean description: 'Whether the custom profile field, display or not on the user card. Must be false for `Users` [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: Before Zulip 12.0 (feature level 476), the "Paragraph" field type was not supported. New in Zulip 6.0 (feature level 146). ' default: false required: type: boolean description: 'Whether an organization administrator has configured this profile field as required. Because the required property is mutable, clients cannot assume that a required custom profile field has a value. The Zulip web application displays a prominent banner to any user who has not set a value for a required field. **Changes**: New in Zulip 9.0 (feature level 244). ' editable_by_user: type: boolean description: 'Whether regular users can edit this profile field on their own account. Note that organization administrators can edit custom profile fields for any user regardless of this setting. **Changes**: New in Zulip 10.0 (feature level 296). ' default: true use_for_user_matching: type: boolean description: 'Whether this custom profile field should be used to match users in typeahead suggestions. Only allowed for Short Text and External Account [profile field types](/help/custom-profile-fields#profile-field-types). This field is only included when its value is `true`. **Changes**: New in Zulip 12.0 (feature level 455). ' default: false required: - id - type - order - name - hint - required - editable_by_user RealmExport: type: object additionalProperties: false description: 'Object containing details about a [data export](/help/export-your-organization). ' properties: id: type: integer description: 'The ID of the data export. ' acting_user_id: type: integer description: 'The ID of the user who created the data export. ' export_time: type: number description: 'The UNIX timestamp of when the data export was started. ' deleted_timestamp: type: number nullable: true description: 'The UNIX timestamp of when the data export was deleted. Will be `null` if the data export has not been deleted. ' failed_timestamp: type: number nullable: true description: 'The UNIX timestamp of when the data export failed. Will be `null` if the data export succeeded, or if it''s still being generated. ' export_url: type: string nullable: true description: 'The URL to download the generated data export. Will be `null` if the data export failed, or if it''s still being generated. ' pending: type: boolean description: 'Whether the data export is pending, which indicates it is still being generated, or if it succeeded, failed or was deleted before being generated. Depending on the size of the organization, it can take anywhere from seconds to an hour to generate the data export. ' export_type: type: string enum: - public - full_with_consent - full_without_consent description: "Whether the data export is public, full with consent, or full without consent.\n\n- `public` = Public data export.\n- `full_with_consent` = Public and private data export (with consent), which includes private data\n for users who have granted consent.\n- `full_without_consent` = All public and private data, which includes private data for all users.\n\n**Changes**: Zulip 12.0 (feature level 449) changed the type of\nthis field from int to string with `1` being replaced by `public` and\n`2` being replaced by `full_with_consent`. The option `full_without_consent`\nwas added for full exports without member consent.\n\n**Changes**: New in Zulip 10.0 (feature level 304). Previously,\nthe export type was not included in these objects because only\npublic data exports could be created or listed via the API or UI.\n" EmailAddressVisibility: type: integer description: 'The [policy][permission-level] for [which other users][help-email-visibility] in this organization can see the user''s real email address. - 1 = Everyone - 2 = Members only - 3 = Administrators only - 4 = Nobody - 5 = Moderators only **Changes**: New in Zulip 7.0 (feature level 163), replacing the realm-level setting. [permission-level]: /api/roles-and-permissions#permission-levels [help-email-visibility]: /help/configure-email-visibility ' JsonSuccess: allOf: - $ref: '#/components/schemas/JsonSuccessBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} example: msg: '' result: success IgnoredParametersSuccess: allOf: - $ref: '#/components/schemas/IgnoredParametersBase' - additionalProperties: false properties: result: {} msg: {} ignored_parameters_unsupported: {} description: '**Changes**: The [`ignored_parameters_unsupported`][ignored_params] array was added as a possible return value for all REST API endpoint JSON success responses in Zulip 7.0 (feature level 167). Previously, it was added to [`POST /users/me/subscriptions/properties`](/api/update-subscription-settings) in Zulip 5.0 (feature level 111) and to [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults) in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0 (feature level 78) as a return value for the [`PATCH /settings`](/api/update-settings) endpoint. A typical successful JSON response with ignored parameters may look like: [ignored_params]: /api/rest-error-handling#ignored-parameters ' example: ignored_parameters_unsupported: - invalid_param_1 - invalid_param_2 msg: '' result: success IgnoredParametersBase: allOf: - $ref: '#/components/schemas/JsonResponseBase' - required: - result - msg properties: result: enum: - success msg: type: string ignored_parameters_unsupported: $ref: '#/components/schemas/IgnoredParametersUnsupported' 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. ' 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. ' JsonResponseBase: type: object properties: result: type: string RealmDomain: type: object additionalProperties: false properties: domain: type: string description: 'The allowed domain. ' allow_subdomains: type: boolean description: 'Whether subdomains are allowed for this domain. ' required: - domain - allow_subdomains LinkifierPattern: description: 'The [Python regular expression](https://docs.python.org/3/howto/regex.html) that should trigger the linkifier. ' type: string example: '#(?P[0-9]+)' LinkifierURLTemplate: description: 'The [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html) compliant URL template used for the link. If you used named groups in `pattern`, you can insert their content here with `{name_of_group}`. **Changes**: New in Zulip 7.0 (feature level 176). This replaced the `url_format_string` parameter, which was a format string in which named groups'' content could be inserted with `%(name_of_group)s`. ' type: string example: https://github.com/zulip/zulip/issues/{id} CodedError: allOf: - $ref: '#/components/schemas/CodedErrorBase' - additionalProperties: false properties: result: {} msg: {} code: {} RealmEmoji: type: object additionalProperties: false description: 'Object containing details about an emoji. It has the following properties: ' properties: id: type: string description: 'The ID for this emoji, same as the object''s key. ' name: type: string description: 'The user-friendly name for this emoji. Users in the organization can use this emoji by writing this name between colons (`:name :`). ' source_url: type: string description: 'The path relative to the organization''s URL where the emoji''s image can be found. ' still_url: type: string nullable: true description: 'Only non-null when the emoji''s image is animated. The path relative to the organization''s URL where a still (not animated) version of the emoji can be found. (This is currently always the first frame of the animation). This is useful for clients to display the emoji in contexts where continuously animating it would be a bad user experience (E.g. because it would be distracting). **Changes**: New in Zulip 5.0 (added as optional field in feature level 97 and then made mandatory, but nullable, in feature level 113). ' deactivated: type: boolean description: 'Whether the emoji has been deactivated or not. ' author_id: type: integer nullable: true description: 'The user ID of the user who uploaded the custom emoji. Will be `null` if the uploader is unknown. **Changes**: New in Zulip 3.0 (feature level 7). Previously was accessible via an `author` object with an `id` field. ' 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. ' responses: SuccessIgnoredParameters: description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/IgnoredParametersSuccess' SimpleSuccess: description: Success. content: application/json: schema: $ref: '#/components/schemas/JsonSuccess' 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. '