Zulip server_and_organizations API
The server_and_organizations API from Zulip — 16 operation(s) for server_and_organizations.
OpenAPI Specification
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 th
# --- truncated at 32 KB (114 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zulip/refs/heads/main/openapi/zulip-server-and-organizations-api-openapi.yml