Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/zerver/openapi/zulip.yaml

16527 lines
755 KiB
YAML
Raw Blame History

# This file contains the API definitions for the Zulip REST API.
#
# For details on the OpenAPI specification, see https://swagger.io/specification
#
# Our own documentation lives at
#
# https://zulip.readthedocs.io/en/latest/documentation/openapi.html
#
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST 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:
# Zulip Cloud
- url: "https://{subdomain}.zulipchat.com/api/v1"
variables:
subdomain:
default: example
# Self-hosted
- url: "{server}/api/v1"
variables:
server:
default: https://
# chat.zulip.org
- url: "https://chat.zulip.org/api/v1"
# Development server
- url: "http://localhost:9991/api/v1"
security:
- basicAuth: []
#######################
# Endpoint definitions
#######################
paths:
/fetch_api_key:
post:
operationId: fetch-api-key
summary: Fetch an API key (production)
tags: ["authentication"]
description: |
This API endpoint is used by clients such as the Zulip mobile and
terminal apps to implement password-based authentication. Given the
user's Zulip login credentials, it returns a Zulip API key that the client
can use to make requests as the user.
This endpoint is only useful for Zulip servers/organizations with
EmailAuthBackend or LDAPAuthBackend enabled.
The Zulip mobile apps also support SSO/social authentication (GitHub
auth, Google auth, SAML, etc.) that does not use this endpoint. Instead,
the mobile apps reuse the web login flow passing the `mobile_flow_otp` in
a webview, and the credentials are returned to the app (encrypted) via a redirect
to a `zulip://` URL.
!!! warn ""
**Note:** If you signed up using passwordless authentication and
never had a password, you can [reset your password](/help/change-your-password).
See the [API keys](/api/api-keys) documentation for
more details on how to download API key manually.
In a [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
see also [the unauthenticated variant](/api/dev-fetch-api-key).
parameters:
- name: username
in: query
description: |
The username to be used for authentication (typically, the email
address, but depending on configuration, it could be an LDAP username).
See the `require_email_format_usernames` parameter documented in
[GET /server_settings](/api/get-server-settings) for details.
schema:
type: string
example: iago@zulip.com
required: true
- name: password
in: query
schema:
type: string
example: abcd1234
description: |
The user's Zulip password (or LDAP password, if LDAP authentication is in use).
required: true
security: []
responses:
"200":
description: |
Valid credentials the client can use to access the Zulip API:
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiKeyResponse"
- $ref: "#/components/schemas/SuccessDescription"
/dev_fetch_api_key:
post:
operationId: dev-fetch-api-key
summary: Fetch an API key (development only)
tags: ["authentication"]
description: |
For easy testing of mobile apps and other clients and against Zulip
development servers, we support fetching a Zulip API key for any user
on the development server without authentication (so that they can
implement analogues of the one-click login process available for Zulip
development servers on the web).
**Note:** This endpoint is only available on Zulip development
servers; for obvious security reasons it will always return an error
in a Zulip production server.
`POST {{ api_url }}/v1/dev_fetch_api_key`
parameters:
- name: username
in: query
description: |
The email address for the user that owns the API key.
schema:
type: string
example: iago@zulip.com
required: true
security: []
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiKeyResponse"
- $ref: "#/components/schemas/SuccessDescription"
/events:
get:
operationId: get-events
summary: Get events from an event queue
tags: ["real_time_events"]
description: |
`GET {{ api_url }}/v1/events`
This endpoint allows you to receive new events from
[a registered event queue](/api/register-queue).
Long-lived clients should use the
`event_queue_longpoll_timeout_seconds` property returned by
`POST /register` as the client-side HTTP request timeout for
calls to this endpoint. It is guaranteed to be higher than
heartbeat frequency and should be respected by clients to
avoid breaking when heartbeat frequency increases.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- queue_id
- last_event_id
x-parameter-description: |
**Note**: The parameters documented above are optional in the sense that
even if you haven't registered a queue by explicitly requesting the
`{{ api_url}}/v1/register` endpoint, you could pass the parameters for
[the `{{ api_url}}/v1/register` endpoint](/api/register-queue) to this
endpoint and a queue would be registered in the absence of a `queue_id`.
x-python-examples-extra-imports: ["sys"]
parameters:
- $ref: "#/components/parameters/QueueId"
- name: last_event_id
in: query
description: |
The highest event ID in this queue that you've received and
wish to acknowledge. See the [code for
`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)
in the [zulip Python
module](https://github.com/zulip/python-zulip-api) for an
example implementation of correctly processing each event
exactly once.
schema:
type: integer
example: -1
- name: dont_block
in: query
description: |
Set to `true` if the client is requesting a nonblocking reply. If not
specified, the request will block until either a new event is available
or a few minutes have passed, in which case the server will send the
client a heartbeat event.
schema:
type: boolean
default: false
example: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
events:
type: array
description: |
An array of `event` objects (possibly zero-length if `dont_block` is
set) with IDs newer than `last_event_id`. Event IDs are
guaranteed to be increasing, but they are not guaranteed to be
consecutive.
items:
oneOf:
- type: object
description: |
Event sent to a user's clients when that user's set of configured
[alert words](/help/pm-mention-alert-notifications#alert-words) have changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- alert_words
alert_words:
type: array
description: |
Array of strings, each a configured alert word.
items:
type: string
additionalProperties: false
example:
{
"type": "alert_words",
"alert_words": ["alert_word"],
"id": 0,
}
- type: object
description: |
Event sent to clients that have requested the
`update_display_settings` event type and did not include
`user_settings_object` in their `client_capabilities` when
registering the event queue.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
deprecated: true
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_display_settings
setting_name:
type: string
description: |
Name of the changed display setting.
setting:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: |
Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
type: string
additionalProperties: false
example:
{
"type": "update_display_settings",
"setting_name": "high_contrast_mode",
"setting": false,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's [notification
settings](/api/update-settings) have changed with an additional
rule that it is only sent to clients that did not include
`user_settings_object` in their `client_capabilities` when
registering the event queue.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
deprecated: true
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_global_notifications
notification_name:
type: string
description: |
Name of the changed notification setting.
setting:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
additionalProperties: false
example:
{
"type": "update_global_notifications",
"notification_name": "enable_sounds",
"setting": true,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's settings
have changed.
**Changes**: New in Zulip 5.0 (feature level 89), replacing the
previous `update_display_settings` and `update_global_notifications`
event types, which are still present for backwards compatibility reasons.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_settings
op:
type: string
enum:
- update
property:
type: string
description: |
Name of the changed setting.
value:
description: |
New value of the changed setting.
oneOf:
- type: boolean
- type: integer
- type: string
language_name:
description: |
Present only if the setting to be changed is
`default_language`. Contains the name of the
new default language in English.
type: string
additionalProperties: false
example:
{
"type": "user_settings",
"op": "update",
"property": "high_contrast_mode",
"value": false,
"id": 0,
}
- type: object
description: |
Event sent generally to all users in an organization for changes
in the set of users or those users metadata.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- update
person:
description: |
Object containing the changed details of the user.
It has multiple forms depending on the value changed.
oneOf:
- type: object
description: |
When a user changes their full name.
properties:
user_id:
type: integer
description: |
The ID of modified user.
full_name:
type: string
description: |
The new full name for the user.
additionalProperties: false
- type: object
description: |
When a user changes their avatar.
properties:
user_id:
type: integer
description: |
The ID of the user who is affected by this change.
avatar_url:
type: string
description: |
The URL of the new avatar for the user.
avatar_source:
type: string
description: |
The new avatar data source type for the user.
Value values are `G` (gravatar) and `U` (uploaded by user).
avatar_url_medium:
type: string
description: |
The new medium-size avatar URL for user.
avatar_version:
type: integer
description: |
The version number for the user's avatar. This is useful
for cache-busting.
additionalProperties: false
- type: object
additionalProperties: false
description: |
When a user changes their time zone setting.
properties:
user_id:
type: integer
description: |
The ID of modified user.
email:
type: string
description: |
The email of the user.
**Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`.
deprecated: true
timezone:
type: string
description: |
The new time zone of the user.
- type: object
additionalProperties: false
description: |
When the owner of a bot changes.
properties:
user_id:
type: integer
description: |
The ID of the user/bot whose owner has changed.
bot_owner_id:
type: integer
description: |
The user id of the new bot owner.
- type: object
additionalProperties: false
description: |
When the [role](/help/roles-and-permissions) of a user changes.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
role:
type: integer
description: |
The new [role](/api/roles-and-permissions) of the user.
enum:
- 100
- 200
- 300
- 400
- 600
- type: object
additionalProperties: false
description: |
When billing role of a user changes.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
is_billing_admin:
type: boolean
description: |
A boolean specifying whether the user is now a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
- type: object
additionalProperties: false
description: |
When the delivery email of a user changes.
Note: This event is only visible to admins.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
delivery_email:
type: string
description: |
The new delivery email of the user.
- type: object
additionalProperties: false
description: |
When the user updates one of their custom profile
fields.
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
custom_profile_field:
type: object
additionalProperties: false
description: |
Object containing details about the custom
profile data change.
properties:
id:
type: integer
description: |
The ID of the custom profile field which user updated.
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support Markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
- type: object
additionalProperties: False
description: |
When the Zulip display email address of a user changes,
either due to the user's email address changing, or
due to changes in the organization's
[email address visibility][help-email-visibility].
[help-email-visibility]: /help/restrict-visibility-of-email-addresses
properties:
user_id:
type: integer
description: |
The ID of the user affected by this change.
new_email:
type: string
description: |
The new email of the user.
additionalProperties: false
example:
{
"type": "realm_user",
"op": "update",
"person":
{
"avatar_source": "G",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=3",
"avatar_url_medium": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&s=500&version=3",
"avatar_version": 3,
"user_id": 10,
},
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's stream subscriptions
have changed (either the set of subscriptions or their properties).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- add
subscriptions:
type: array
description: |
A list of dictionaries where each dictionary contains
information about one of the subscribed streams.
items:
$ref: "#/components/schemas/Subscriptions"
additionalProperties: false
example:
{
"type": "subscription",
"op": "add",
"subscriptions":
[
{
"name": "test_stream",
"stream_id": 9,
"description": "",
"rendered_description": "",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
"color": "#76ce90",
"is_muted": false,
"pin_to_top": false,
"audible_notifications": null,
"desktop_notifications": null,
"email_notifications": null,
"push_notifications": null,
"wildcard_mentions_notify": null,
"in_home_view": true,
"email_address": "test_stream.af64447e9e39374841063747ade8e6b0.show-sender@testserver",
"stream_weekly_traffic": null,
"subscribers": [10],
},
],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user has been unsubscribed
from one or more streams.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- remove
subscriptions:
type: array
description: |
A list of dictionaries, where each dictionary contains
information about one of the newly unsubscribed streams.
items:
type: object
additionalProperties: false
description: |
Dictionary containing details about the unsubscribed stream.
properties:
stream_id:
type: integer
description: |
The ID of the stream.
name:
type: string
description: |
The name of the stream.
additionalProperties: false
example:
{
"type": "subscription",
"op": "remove",
"subscriptions":
[{"name": "test_stream", "stream_id": 9}],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when a property of the user's
subscription to a stream has been updated. This event is used
only for personal properties like `is_muted`; see the `stream` event
for global properties of a stream.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- update
stream_id:
type: integer
description: |
The ID of the stream whose subscription details have changed.
property:
type: string
description: |
The property of the subscription which has changed. See
[/users/me/subscriptions/properties GET](/api/update-subscription-settings)
for details on the various properties of a stream.
Clients should generally handle an unknown property received here without
crashing, since that will naturally happen when connecting to a Zulip
server running a new version that adds a new subscription property.
value:
description: |
The new value of the changed property.
oneOf:
- type: integer
- type: boolean
- type: string
additionalProperties: false
example:
{
"op": "update",
"type": "subscription",
"property": "pin_to_top",
"value": true,
"stream_id": 11,
"id": 0,
}
- type: object
description: |
Event sent to other users when users have been subscribed to
streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- peer_add
stream_ids:
type: array
description: |
The IDs of the streams to which the user has subscribed.
items:
type: integer
user_ids:
type: array
description: |
The IDs of the users who subscribed.
items:
type: integer
additionalProperties: false
example:
{
"type": "subscription",
"op": "peer_add",
"stream_id": 9,
"user_id": 12,
"id": 0,
}
- type: object
description: |
Event sent to other users when users have been unsubscribed
from streams. Sent to all users if the stream is public or to only
the existing subscribers if the stream is private.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- subscription
op:
type: string
enum:
- peer_remove
stream_ids:
type: array
description: |
The IDs of the streams from which the users have been
unsubscribed from.
items:
type: integer
user_ids:
type: array
description: |
The IDs of the users who have been unsubscribed.
items:
type: integer
additionalProperties: false
example:
{
"type": "subscription",
"op": "peer_remove",
"stream_id": 9,
"user_id": 12,
"id": 0,
}
- type: object
description: |
Event type for messages.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- message
message:
$ref: "#/components/schemas/MessagesEvent"
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
Clients should inspect the flags field rather than assuming that
new messages are unread; [muted users](/api/mute-user), messages
sent by the current user, and more subtle scenarios can result
in a new message that the server has already marked as read for
the user.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
additionalProperties: false
example:
{
"type": "message",
"message":
{
"id": 31,
"sender_id": 10,
"content": '<p>First message ...<a href="user_uploads/2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt">zulip.txt</a></p>',
"recipient_id": 23,
"timestamp": 1594825416,
"client": "test suite",
"subject": "test",
"topic_links": [],
"is_me_message": false,
"reactions": [],
"submessages": [],
"sender_full_name": "King Hamlet",
"sender_short_name": "hamlet",
"sender_email": "user10@zulip.testserver",
"sender_realm_str": "zulip",
"display_recipient": "Denmark",
"type": "stream",
"stream_id": 1,
"avatar_url": null,
"content_type": "text/html",
},
"flags": [],
"id": 1,
}
- type: object
description: |
Event sent to a user's clients when the user completes the
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
to know whether initiating Zoom OAuth is required before creating a Zoom call.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- has_zoom_token
value:
type: boolean
description: |
A boolean specifying whether the user has zoom
token or not.
additionalProperties: false
example:
{
"type": "has_zoom_token",
"value": true,
"id": 0,
}
- type: object
description: |
A simple event sent to organization administrators when the
set of invitations changes; this tells clients they need to refetch
data from `GET /invites` if they are displaying UI containing active
invitations.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- invites_changed
additionalProperties: false
example: {"type": "invites_changed", "id": 0}
- type: object
description: |
Event sent to all users in a Zulip organization when a new
user joins. Processing this event is important to being able
to display basic details on other users given only their ID.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- add
person:
$ref: "#/components/schemas/User"
additionalProperties: false
example:
{
"type": "realm_user",
"op": "add",
"person":
{
"email": "foo@zulip.com",
"user_id": 38,
"avatar_version": 1,
"is_admin": false,
"is_owner": false,
"is_guest": false,
"is_billing_admin": false,
"role": 400,
"is_bot": false,
"full_name": "full name",
"timezone": "",
"is_active": true,
"date_joined": "2020-07-15T15:04:02.030833+00:00",
"avatar_url": "https://secure.gravatar.com/avatar/c6b5578d4964bd9c5fae593c6868912a?d=identicon&version=1",
"profile_data": {},
},
"id": 0,
}
- type: object
description: |
Event sent to all users in a Zulip organization when
a user is deactivated.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user
op:
type: string
enum:
- remove
person:
type: object
additionalProperties: false
description: |
Object containing details of the deactivated user.
properties:
user_id:
type: integer
description: |
The ID of the deactivated user.
full_name:
type: string
deprecated: true
description: |
The full name of the user.
**Deprecated**: We expect to remove this field in the future.
additionalProperties: false
example:
{
"type": "realm_user",
"op": "remove",
"person":
{"user_id": 35, "full_name": "Foo Bot"},
"id": 0,
}
- type: object
description: |
Event sent to all users in an organization when a user comes
back online after being long offline. While most presence updates happen
done via polling the main presence endpoint, this event is important
to avoid confusing users when someone comes online and then immediately sends
a message (one wouldn't want them to still appear offline at that point!).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- presence
user_id:
type: integer
description: |
The ID of modified user.
email:
type: string
description: |
The email of the user.
**Deprecated**: This field will be removed in a future
release as it is redundant with the `user_id`.
deprecated: true
server_timestamp:
type: number
description: |
The timestamp of when the Zulip server received the user's
presence as a UNIX timestamp.
presence:
type: object
description: |
An object contatining a set of objects which describe the
the user's presence on various platforms.
additionalProperties:
$ref: "#/components/schemas/Presence"
additionalProperties: false
example:
{
"type": "presence",
"user_id": 10,
"email": "user10@zulip.testserver",
"server_timestamp": 1594825445.320078373,
"presence":
{
"ZulipAndroid/1.0":
{
"client": "ZulipAndroid/1.0",
"status": "idle",
"timestamp": 1594825445,
"pushable": false,
},
},
"id": 0,
}
- type: object
description: |
Event sent when a new stream is created to users who can see
the new stream exists (for private streams, only subscribers and
organization administrators will receive this event).
Note that organization administrators who are not subscribed will
not be able to see content on the stream; just that it exists.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- create
streams:
type: array
description: |
Array of stream objects, each containing
details about the newly added stream(s).
items:
$ref: "#/components/schemas/BasicStream"
additionalProperties: false
example:
{
"type": "stream",
"op": "create",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"invite_only": true,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": false,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
},
],
"id": 0,
}
- type: object
description: |
Event sent to all users who can see a stream when it is deactivated.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- delete
streams:
type: array
description: |
Array of stream objects, each contatining
details about a stream that was deleted.
items:
$ref: "#/components/schemas/BasicStream"
additionalProperties: false
example:
{
"type": "stream",
"op": "delete",
"streams":
[
{
"name": "private",
"stream_id": 12,
"description": "",
"rendered_description": "",
"invite_only": true,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": false,
"first_message_id": null,
"message_retention_days": null,
"is_announcement_only": false,
},
],
"id": 0,
}
- type: object
description: |
Event sent to all users who can see that a stream exists
when a property of that stream changes.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- stream
op:
type: string
enum:
- update
stream_id:
type: integer
description: |
The ID of the stream whose details have changed.
name:
type: string
description: |
The name of the stream whose details have changed.
property:
type: string
description: |
The property of the stream which has changed. See
[/stream GET](/api/get-streams) for details on the various
properties of a stream.
Clients should handle an "unknown" property received here without
crashing, since that can happen when connecting to a server running a
newer version of Zulip with new features.
value:
description: |
The new value of the changed property.
oneOf:
- type: integer
- type: boolean
- type: string
rendered_description:
type: string
description: |
Note: Only present if the changed property was `description`.
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
history_public_to_subscribers:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
is_web_public:
type: boolean
description: |
Note: Only present if the changed property was `invite_only`.
Whether the stream's history is now readable by web-public spectators.
**Changes**: New in Zulip 5.0 (feature level 71).
additionalProperties: false
example:
{
"op": "update",
"type": "stream",
"property": "invite_only",
"value": true,
"history_public_to_subscribers": true,
"is_web_public": false,
"stream_id": 11,
"name": "test_stream",
"id": 0,
}
- type: object
description: |
Event sent when a reaction is added to a message.
Sent to all users who were recipients of the message.
allOf:
- $ref: "#/components/schemas/EmojiReactionBase"
- additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- reaction
op:
type: string
enum:
- add
message_id:
type: integer
description: |
The ID of the message to which a reaction was
added.
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id: {}
user: {}
example:
{
"type": "reaction",
"op": "add",
"user_id": 10,
"user":
{
"user_id": 10,
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
},
"message_id": 32,
"emoji_name": "tada",
"emoji_code": "1f389",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
description: |
Event sent when a reaction is removed from a message.
Sent to all users who were recipients of the message.
allOf:
- $ref: "#/components/schemas/EmojiReactionBase"
- additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- reaction
op:
type: string
enum:
- remove
message_id:
type: integer
description: |
The ID of the message from which the reaction was
removed.
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id: {}
user: {}
example:
{
"type": "reaction",
"op": "remove",
"user_id": 10,
"user":
{
"user_id": 10,
"email": "user10@zulip.testserver",
"full_name": "King Hamlet",
},
"message_id": 52,
"emoji_name": "tada",
"emoji_code": "1f389",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when the user uploads a new file
in a Zulip message. Useful to implement live update in UI showing all files
the current user has uploaded.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- add
attachment:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "add",
"attachment":
{
"id": 1,
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6,
"create_time": 1594825414000,
"messages": [],
},
"upload_space_used": 6,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when details of a file that user
uploaded are changed. Most updates will be changes in the list of
messages that reference the uploaded file.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- update
attachment:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "update",
"attachment":
{
"id": 1,
"name": "zulip.txt",
"path_id": "2/ce/2Xpnnwgh8JWKxBXtTfD6BHKV/zulip.txt",
"size": 6,
"create_time": 1594825414000,
"messages": [],
},
"upload_space_used": 6,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user's clients when the user deletes a file
they had uploaded. Useful primarily for UI showing all the files
the current user has uploaded.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- attachment
op:
type: string
enum:
- remove
attachment:
type: object
description: |
Dictionary containing the id of the deleted attachment.
additionalProperties: false
properties:
id:
type: integer
description: |
The ID of the deleted attachment.
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"type": "attachment",
"op": "remove",
"attachment": {"id": 1},
"upload_space_used": 0,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a submessage is added to a message.
Submessages are an **experimental** API used for widgets such as the
`/poll` widget in Zulip.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- submessage
msg_type:
type: string
description: |
The type of the message.
content:
type: string
description: |
The new content of the submessage.
message_id:
type: integer
description: |
The ID of the message to which the submessage has been added.
sender_id:
type: integer
description: |
The ID of the user who sent the message.
submessage_id:
type: integer
description: |
The ID of the submessage.
example:
{
"type": "submessage",
"msg_type": "widget",
"message_id": 970461,
"submessage_id": 4737,
"sender_id": 58,
"content": '{"type":"vote","key":"58,1","vote":1}',
"id": 28,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
status of a user changes.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_status
away:
type: boolean
description: |
Whether the user has marked themself "away" with this status.
status_text:
type: string
description: |
The text content of the status message.
This will be `""` for users who set a status without selecting
or writing a message.
emoji_name:
type: string
description: |
The [emoji name](/api/update-status#parameter-emoji_name) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
emoji_code:
type: string
description: |
The [emoji code](/api/update-status#parameter-emoji_code) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
reaction_type:
type: string
description: |
The [emoji type](/api/update-status#parameter-reaction_type) for
the emoji the user selected for their new status.
This will be `""` for users who set a status without selecting
an emoji.
**Changes**: New in Zulip 5.0 (feature level 86).
user_id:
type: integer
description: |
The ID of the user whose status changed.
example:
{
"type": "user_status",
"user_id": 10,
"away": true,
"status_text": "out to lunch",
"emoji_name": "car",
"emoji_code": "1f697",
"reaction_type": "unicode_emoji",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when new custom
profile field types are configured for that Zulip organization.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- custom_profile_fields
fields:
type: array
description: |
An array of dictionaries where each dictionary contains
details of a single new custom profile field for the Zulip
organization.
items:
$ref: "#/components/schemas/CustomProfileField"
example:
{
"type": "custom_profile_fields",
"fields":
[
{
"id": 1,
"name": "Phone number",
"type": 1,
"hint": "",
"field_data": "",
"order": 1,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
},
{
"id": 4,
"name": "Favorite editor",
"type": 3,
"hint": "",
"field_data": '{"vim":{"text":"Vim","order":"1"},"emacs":{"text":"Emacs","order":"2"}}',
"order": 4,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when an organization
administrator changes the organization's configured default stream groups.
Default stream groups are an **experimental** feature that is not yet
stabilized.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- default_stream_groups
default_stream_groups:
type: array
description: |
An array of dictionaries where each dictionary
contains details about a single default stream group.
items:
$ref: "#/components/schemas/DefaultStreamGroup"
example:
{
"type": "default_stream_groups",
"default_stream_groups":
[
{
"name": "group1",
"id": 2,
"description": "New description",
"streams":
[
{
"name": "Scotland",
"stream_id": 3,
"description": "Located in the United Kingdom",
"rendered_description": "<p>Located in the United Kingdom</p>",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 1,
"message_retention_days": null,
"is_announcement_only": false,
},
{
"name": "Denmark",
"stream_id": 1,
"description": "A Scandinavian country",
"rendered_description": "<p>A Scandinavian country</p>",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 4,
"message_retention_days": null,
"is_announcement_only": false,
},
{
"name": "Verona",
"stream_id": 5,
"description": "A city in Italy",
"rendered_description": "<p>A city in Italy</p>",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 6,
"message_retention_days": null,
"is_announcement_only": false,
},
],
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
default streams in the organization are changed by an
organization administrator.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- default_streams
default_streams:
type: array
description: |
An array of dictionaries where each dictionary
contains details about a single default stream.
items:
$ref: "#/components/schemas/BasicStream"
example:
{
"type": "default_streams",
"default_streams":
[
{
"name": "Scotland",
"stream_id": 3,
"description": "Located in the United Kingdom",
"rendered_description": "<p>Located in the United Kingdom</p>",
"invite_only": false,
"is_web_public": false,
"stream_post_policy": 1,
"history_public_to_subscribers": true,
"first_message_id": 1,
"message_retention_days": null,
"is_announcement_only": false,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a message has been deleted.
Sent to all users who received the message.
**Changes**: Before Zulip 5.0 (feature level 77), events
for private messages contained additional `sender_id` and
`recipient_id` fields.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- delete_message
message_ids:
type: array
description: |
The `message_ids` property will be present for clients that support
the `bulk_message_deletion` client capability.
An containing the IDs of the newly deleted messages.
items:
type: integer
message_id:
type: integer
description: |
The `message_id` property will be present for clients that do not support
the `bulk_message_deletion` client capability.
The ID of the newly deleted message.
message_type:
type: string
description: |
The type of message. Either 'stream' or 'private'. The other keys
present in the event, necessary to update various frontend data structures
that might be tracking the message, depend on the message type.
enum:
- private
- stream
stream_id:
type: integer
description: |
Only present for stream messages.
The ID of the stream to which the message was sent.
topic:
type: string
description: |
Only present for stream messages.
The topic to which the message was sent.
example:
{
"type": "delete_message",
"message_type": "private",
"message_id": 37,
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's set of
configured muted topics have changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- muted_topics
muted_topics:
type: array
description: |
Array of tuples, where each tuple describes a muted topic.
The first element of tuple is the stream name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
items:
type: array
items:
oneOf:
- type: string
- type: integer
additionalProperties: false
example:
{
"type": "muted_topics",
"muted_topics":
[["Denmark", "topic", 1594825442]],
"id": 0,
}
- type: object
description: |
Event sent to a user's clients when that user's set of
configured [muted users](/api/mute-user) have changed.
**Changes**: New in Zulip 4.0 (feature level 48).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- muted_users
muted_users:
type: array
description: |
A list of dictionaries where each dictionary describes
a muted user.
items:
type: object
additionalProperties: false
description: |
Object containing the user id and timestamp of a muted user.
properties:
id:
type: integer
description: |
The ID of the muted user.
timestamp:
type: integer
description: |
An integer UNIX timestamp representing when the user was muted.
additionalProperties: false
example:
{
"type": "muted_users",
"muted_users":
[
{"id": 1, "timestamp": 1594825442},
{"id": 22, "timestamp": 1654865392},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Heartbeat events are sent by the server to avoid
longpolling connections being affected by networks that
kill idle HTTP connections.
Clients do not need to do anything to process these
events, beyond the common `last_event_id` accounting.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- heartbeat
example: {"type": "heartbeat", "id": 0}
- type: object
additionalProperties: false
description: |
Event sent when the set of onboarding "hotspots" to show for
the current user have changed (E.g. because the user dismissed one).
Clients that feature a similar tutorial experience to the Zulip
web app may want to handle these events.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- hotspots
hotspots:
type: array
description: |
An array of dictionaries where each
dictionary contains details about a single hotspot.
items:
$ref: "#/components/schemas/Hotspot"
example:
{
"type": "hotspots",
"hotspots":
[
{
"name": "intro_streams",
"title": "Catch up on a stream",
"description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
"delay": 0.5,
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a message's content, topic and/or
stream has been edited or when a message's content
has a rendering update, such as for an
[inline URL preview][inline-url-previews].
Sent to all users who had received the original
message.
[inline-url-previews]: https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#inline-url-previews
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message
user_id:
type: integer
nullable: true
description: |
The ID of the user who sent the message.
Null when event is for a rendering update of the original message,
such as for an [inline URL preview][inline-url-previews].
**Changes**: As of Zulip 5.0 (feature level 114), this field
is present for all `update_message` events. Previously, this
field was omitted for [inline URL preview][inline-url-previews]
updates.
rendering_only:
type: boolean
description: |
Whether the event only updates the rendered content of the message.
This field should be used by clients to determine if the event
only provides a rendering update to the message content,
such as for an [inline URL preview][inline-url-previews].
When `True`, the event does not reflect a user-generated edit
and does not modify the message history.
**Changes**: New in Zulip 5.0 (feature level 114). Clients can
correctly identify these rendering update event with earlier
Zulip versions by checking whether the `user_id` field was omitted.
message_id:
type: integer
description: |
The ID of the message which was edited or updated.
This field should be used to apply content edits to the client's
cached message history, or to apply rendered content updates.
If the stream or topic was changed, the set of moved messages is
encoded in the separate `message_ids` field, which is guaranteed
to include `message_id`.
message_ids:
type: array
items:
type: integer
description: |
The list of IDs of messages to which any stream or topic changes
encoded in this event should be applied.
These messages are guaranteed to have all been previously sent
to stream `stream_id` with topic `orig_subject`, and have been
moved to `new_stream_id` with topic `subject` (if those fields
are present in the event).
Clients processing these events should update all cached message
history associated with the moved messages (including adjusting
`unread_msgs` data structures, where the client may not have the
message itself in its history) to reflect the new stream and
topic.
Content changes should be applied only to the single message
indicated by `message_id`.
flags:
type: array
description: |
The user's personal [message flags][message-flags] for the
message with ID `message_id` following the edit.
A client application should compare these to the original flags
to identify cases where a mention or alert word was added by the
edit.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
edit_timestamp:
type: integer
description: |
The time when this message edit operation was processed by the
server.
**Changes**: As of Zulip 5.0 (feature level 114), this field
is present for all `update_message` events. Previously, this
field was omitted for [inline URL preview][inline-url-previews]
updates.
stream_name:
type: string
description: |
Only present if the message was edited and originally sent to a stream.
The name of the stream that the message was sent to. Clients
are recommended to use the `stream_id` field instead.
stream_id:
type: integer
description: |
Only present if the message was edited and originally sent to a stream.
The pre-edit stream for all of the messages with IDs in
`message_ids`.
**Changes**: As of Zulip 5.0 (feature level 112), this field
is present for all edits to a stream message. Previously, it
was not present when only the content of the stream message was
edited.
new_stream_id:
type: integer
description: |
Only present if message(s) were moved to a different stream.
The post-edit stream for all of the messages with IDs in
`message_ids`.
propagate_mode:
type: string
description: |
Only present if this event moved messages to a different
topic and/or stream.
The choice the editing user made about which messages should be
affected by a stream/topic edit:
- `change_one` => Just change the one indicated in `message_id`.
- `change_later` => Change messages in the same topic that had
been sent after this one.
- `change_all`=> Change all messages in that topic.
This parameter should be used to decide whether to change
navigation and compose box state in response to the edit. For
example, if the user was previously in topic narrow, and the
topic was edited with `change_later` or `change_all`, the Zulip
web app will automatically navigate to the new topic narrow.
Similarly, a message being composed to the old topic should
have its recipient changed to the new topic.
This navigation makes it much more convenient to move content
between topics without disruption or messages continuing
to be sent to the pre-edit topic by accident.
enum:
- change_one
- change_later
- change_all
orig_subject:
type: string
description: |
Only present if this event moved messages to a different
topic and/or stream.
The pre-edit topic for all of the messages with IDs in
`message_ids`.
subject:
type: string
description: |
Only present if this event moved messages to a different
topic.
The post-edit topic for all of the messages with IDs in
`message_ids`.
topic_links:
type: array
items:
type: object
additionalProperties: false
properties:
text:
type: string
description: |
The original link text present in the topic.
url:
type: string
description: |
The expanded target url which the link points to.
description: |
Only present if this event moved messages to a different
topic.
Data on any links to be included in the `topic`
line (these are generated by
[custom linkification filter](/help/add-a-custom-linkifier)
that match content in the message's topic.), corresponding
to the post-edit topic.
**Changes**: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1). Previously, this field
was called `subject_links`; clients are recommended to
rename `subject_links` to `topic_links` if present for
compatibility with older Zulip servers.
orig_content:
type: string
description: |
Only present if this event changed the message content.
The original content of the message with ID `message_id`
immediately prior to this edit, in the original markdown.
orig_rendered_content:
type: string
description: |
Only present if this event changed the message content.
The original content of the message with ID `message_id`
immediately prior to this edit, rendered as HTML.
prev_rendered_content_version:
type: integer
description: |
Only present if this event changed the message content.
The Markdown processor version number for the pre-edit message.
Clients should ignore this field.
content:
type: string
description: |
Only present if this event changed the message content or
updated the message content for an
[inline URL preview][inline-url-previews].
The new content of the message with ID `message_id`, in the
original Markdown.
rendered_content:
type: string
description: |
Only present if this event changed the message content or
updated the message content for an
[inline URL preview][inline-url-previews].
The new content of the message with ID `message_id`,
rendered in HTML.
is_me_message:
type: boolean
description: |
Only present if this event changed the message content.
Whether the message with ID `message_id` is now a
[/me status message][status-messages].
[status-messages]: /help/format-your-message-using-markdown#status-messages
required:
- type
- id
- user_id
- message_id
- message_ids
- flags
- edit_timestamp
- rendering_only
example:
{
"type": "update_message",
"user_id": 10,
"edit_timestamp": 1594825451,
"message_id": 58,
"stream_name": "Verona",
"orig_content": "hello",
"orig_rendered_content": "<p>hello</p>",
"content": "new content",
"rendered_content": "<p>new content</p>",
"prev_rendered_content_version": 1,
"is_me_message": false,
"propagate_mode": "change_all",
"stream_id": 5,
"orig_subject": "test",
"subject": "new_topic",
"topic_links": [],
"message_ids": [58, 57],
"flags": [],
"rendering_only": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a user starts typing a message.
Sent to all clients for users who would receive the
message being typed, with the additional rule that typing
notifications for stream messages are only sent to clients
that included `stream_typing_notifications` in their
`client_capabilities` when registering the event queue.
**Changes**: Typing notifications for stream messages are new in
Zulip 4.0 (feature level 58).
See the [typing endpoint docs](/api/set-typing-status) for more details.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- typing
op:
type: string
enum:
- start
message_type:
type: string
description: |
Type of message being composed. Must be "stream" or "private",
as with sending a message.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
all typing notifications were implicitly private `private`.
enum:
- private
- stream
sender:
additionalProperties: false
type: object
description: |
Object describing the "sender" (i.e. the user who is typing a message).
properties:
user_id:
type: integer
description: |
The user's ID.
email:
type: string
description: |
The Zulip display email address for the user.
recipients:
type: array
description: |
Only present if `message_type` is `private`.
Array of dictionaries describing the set of users who would be recipients
of the message being typed. Each dictionary contains details on one
one of the recipients users; the sending user is guaranteed to appear
among the recipients.
items:
type: object
additionalProperties: false
description: |
Object containing the user id and email of a recipient.
properties:
user_id:
type: integer
description: |
The ID of the user.
email:
type: string
description: |
The Zulip display email address for the user.
stream_id:
type: integer
description: |
Only present if `message_type` is `stream`.
The unique ID of the stream to which message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
topic:
type: string
description: |
Only present if `message_type` is `stream`.
Topic within the stream where the message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
example:
{
"type": "typing",
"op": "start",
"sender":
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
"recipients":
[
{
"user_id": 8,
"email": "user8@zulip.testserver",
},
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent when a user stops typing a message.
Sent to all clients for users who would receive the message
that was previously being typed, with the additional rule
that typing notifications for stream messages are only sent to
clients that included `stream_typing_notifications` in their
`client_capabilities` when registering the event queue.
**Changes**: Typing notifications for stream messages are new in
Zulip 4.0 (feature level 58).
See the [typing endpoint docs](/api/set-typing-status) for more details.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- typing
op:
type: string
enum:
- stop
message_type:
type: string
description: |
Type of message being composed. Must be "stream" or "private",
as with sending a message.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
all typing notifications were implicitly private `private`.
enum:
- private
- stream
sender:
additionalProperties: false
type: object
description: |
Object describing the "sender" (i.e. the user who was previously
typing a message).
properties:
user_id:
type: integer
description: |
The user's ID.
email:
type: string
description: |
The Zulip display email address for the user.
recipients:
type: array
description: |
Only present for typing notifications for (group) private messages.
Array of dictionaries describing the set of users who would be recipients
of the message that stopped being typed. Each dictionary contains
details on one one of the recipients users; the sending user is
guaranteed to appear among the recipients.
items:
type: object
additionalProperties: false
description: |
Object containing the user id and email of a recipient.
properties:
user_id:
type: integer
description: |
The ID of the user.
email:
type: string
description: |
The Zulip display email address for the user.
stream_id:
type: integer
description: |
Only present if `message_type` is `stream`.
The unique ID of the stream to which message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
topic:
type: string
description: |
Only present if `message_type` is `stream`.
Topic within the stream where the message is being typed.
**Changes**: New in Zulip 4.0 (feature level 58). Previously,
typing notifications were only for private messages.
example:
{
"type": "typing",
"op": "stop",
"sender":
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
"recipients":
[
{
"user_id": 8,
"email": "user8@zulip.testserver",
},
{
"user_id": 10,
"email": "user10@zulip.testserver",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user when [message flags][message-flags] are added
to a message.
[message-flags]: /api/update-message-flags#available-flags
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message_flags
op:
type: string
enum:
- add
operation:
deprecated: true
description: |
Old name for `op` for this event type.
**Deprecated**: This is deprecated; please use `op` instead
starting with Zulip 4.0 (feature level 32).
type: string
enum:
- add
flag:
type: string
description: |
The flag that was added.
messages:
type: array
description: |
Array containing the ids of all messages to which
the flag was added.
items:
type: integer
all:
type: boolean
description: |
Whether the flag was added to all messages (E.g. all messages
were marked as read).
If this is true, then the `messages` array will be empty.
example:
{
"type": "update_message_flags",
"op": "add",
"operation": "add",
"flag": "starred",
"messages": [63],
"all": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to a user when [message flags][message-flags] are
removed from a message.
[message-flags]: /api/update-message-flags#available-flags
required:
[
"id",
"type",
"op",
"operation",
"flag",
"messages",
"all",
]
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- update_message_flags
op:
type: string
enum:
- remove
operation:
deprecated: true
type: string
description: |
Old name for `op` for this event type.
**Deprecated**: This is deprecated; please use `op` instead
starting with Zulip 4.0 (feature level 32).
enum:
- remove
flag:
type: string
description: |
The flag to be removed.
enum:
- starred
- read
messages:
type: array
description: |
Array containing the IDs of the messages from which the flag
was removed.
items:
type: integer
all:
type: boolean
description: |
Whether the flag was removed from all messages.
If this is true then the `messages` array will be empty.
message_details:
description: |
Present if `message` and `update_message_flags` are both present in
`event_types` and the `flag` is `read` and the `op` is `remove`.
A set of data structures describing the messages that
are being marked as unread with additional details to
allow a client to update the `unread_msgs` data
structure for these messages (which may not be
otherwise known to the client).
**Changes**: New in Zulip 5.0 (feature level 121). Previously,
marking already read messages as unread was not
supported by the Zulip API.
type: object
additionalProperties:
type: object
description: |
Additional properties.
additionalProperties: false
required: ["type"]
properties:
type:
type: string
description: |
The type of this message.
enum:
- private
- stream
mentioned:
type: boolean
description: |
A flag which indicates whether the message contains a mention
of the user.
Present only if the message mentions the current user.
user_ids:
type: array
items:
type: integer
description: |
Present only if `type` is `private`.
The user IDs of every recipient of this private message, excluding yourself.
Will be the empty list for a message you had sent to only yourself.
stream_id:
type: integer
description: |
Present only if `type` is `stream`.
The ID of the stream where the message was sent.
topic:
type: string
description: |
Present only if `type` is `stream`.
Name of the topic where the message was sent.
unmuted_stream_msg:
type: boolean
deprecated: true
description: |
**Deprecated**
Internal implementation detail. Clients should
ignore this field as it will be removed in the future.
example:
{
"type": "update_message_flags",
"op": "remove",
"operation": "remove",
"flag": "starred",
"messages": [63],
"message_details":
{
63:
{
"type": "stream",
"stream_id": 22,
"topic": "lunch",
},
},
"all": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to users in an organization when a [user group](/help/user-groups) is created.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add
group:
$ref: "#/components/schemas/UserGroup"
example:
{
"type": "user_group",
"op": "add",
"group":
{
"name": "backend",
"members": [12],
"description": "Backend team",
"id": 2,
"is_system_group": false,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization
when a property of a user group is changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- update
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
data:
type: object
additionalProperties: false
description: |
Dictionary containing the changed details of the user group.
properties:
name:
type: string
description: |
The new name of the user group. Only present if the group's name changed.
description:
type: string
description: |
The new description of the group. Only present if the description
changed.
example:
{
"type": "user_group",
"op": "update",
"group_id": 2,
"data":
{
"description": "Mention this group to get the security team's attention.",
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when users have been added to a user group.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add_members
group_id:
type: integer
description: |
The ID of the user group with new members.
user_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the users who have been added
to the user group.
example:
{
"type": "user_group",
"op": "add_members",
"group_id": 2,
"user_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when users have been removed from
a user group.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove_members
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
user_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the users who have been removed
from the user group.
example:
{
"type": "user_group",
"op": "remove_members",
"group_id": 2,
"user_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when subgroups have been added to
a user group.
**Changes**: New in Zulip 6.0 (feature level 127).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- add_subgroups
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
subgroup_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the subgroups that have been added
to the user group.
example:
{
"type": "user_group",
"op": "add_subgroups",
"group_id": 2,
"subgroup_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when subgroups have been removed from
a user group.
**Changes**: New in Zulip 6.0 (feature level 127).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove_subgroups
group_id:
type: integer
description: |
The ID of the user group whose details have changed.
subgroup_ids:
type: array
items:
type: integer
description: |
Array containing the IDs of the subgroups that have been
removed from the user group.
example:
{
"type": "user_group",
"op": "remove_subgroups",
"group_id": 2,
"subgroup_ids": [10],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a user group has been deleted.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- user_group
op:
type: string
enum:
- remove
group_id:
type: integer
description: |
The ID of the group which has been deleted.
example:
{
"type": "user_group",
"op": "remove",
"group_id": 2,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
set of configured [linkifiers](/help/add-a-custom-linkifier)
for the organization has changed.
Processing this event is important to doing Markdown local echo
correctly.
**Changes**: New in Zulip 4.0 (feature level 54), replacing the
previous `realm_filters` event type, which is still sent for
backwards compatibility reasons.
Clients should migrate to requesting and processing the
`realm_linkifiers` event type when possible, since we plan to remove
the legacy `realm_filters` logic entirely in a future release.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_linkifiers
realm_linkifiers:
type: array
description: |
Array of dictionaries where each dictionary contains details about
a single realm linkifier.
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The string regex pattern which represents the pattern that
should be linkified by this linkifier.
url_format:
type: string
description: |
The URL format string to be used for linkifying matches.
id:
type: integer
description: |
The ID of the linkifier.
example:
{
"type": "realm_linkifiers",
"realm_linkifiers":
[
{
"pattern": "#(?P<id>[123])",
"url_format": "https://realm.com/my_realm_filter/%(id)s",
"id": 1,
},
],
"id": 0,
}
- type: object
additionalProperties: false
deprecated: true
description: |
Legacy event type. Sent to all users in a Zulip organization
when the set of configured [linkifiers](/help/add-a-custom-linkifier)
for the organization has changed.
**Changes**: Deprecated in Zulip 4.0 (feature level 54), replaced by
the `realm_linkifiers` event type, which has a clearer name and format,
instead.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_filters
realm_filters:
type: array
items:
type: array
items:
oneOf:
- type: integer
- type: string
description: |
An array of tuples, where each tuple describes a linkifier.
The first element of the tuple is a
string regex pattern which represents the pattern that should
be linkified on matching. The second element is the URL with which the
pattern matching string should be linkified with and the third element
is the ID of the realm filter.
example:
{
"type": "realm_filters",
"realm_filters":
[
[
"#(?P<id>[123])",
"https://realm.com/my_realm_filter/%(id)s",
1,
],
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
set of configured [code playgrounds](/help/code-blocks#code-playgrounds)
for the organization has changed.
**Changes**: New in Zulip 4.0 (feature level 49).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_playgrounds
realm_playgrounds:
type: array
description: |
An array of dictionaries where each dictionary contains
data about a single playground entry.
items:
$ref: "#/components/schemas/RealmPlayground"
example:
{
"type": "realm_playgrounds",
"realm_playgrounds":
[
{
"id": 1,
"name": "Python playground",
"pygments_language": "Python",
"url_prefix": "https://python.example.com",
},
],
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when
a [custom emoji](/help/custom-emoji) has been updated,
typically when a new emoji has been added or an old one
has been deactivated. The event contains all custom emoji
configured for the organization, not just the updated
custom emoji.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_emoji
op:
type: string
enum:
- update
realm_emoji:
type: object
description: |
An object in which each key describes a realm emoji.
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
example:
{
"type": "realm_emoji",
"op": "update",
"realm_emoji":
{
"2":
{
"id": "2",
"name": "my_emoji",
"source_url": "/user_avatars/2/emoji/images/2.png",
"deactivated": true,
"author_id": 11,
},
"1":
{
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/2/emoji/images/1.png",
"deactivated": false,
"author_id": 11,
},
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- add
realm_domain:
$ref: "#/components/schemas/RealmDomain"
example:
{
"type": "realm_domains",
"op": "add",
"realm_domain":
{
"domain": "zulip.org",
"allow_subdomains": false,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- change
realm_domain:
type: object
additionalProperties: false
description: |
Object containing details of the edited domain.
properties:
domain:
type: string
description: |
The domain whose settings have changed.
allow_subdomains:
type: boolean
description: |
Whether subdomains are allowed for this domain.
example:
{
"type": "realm_domains",
"op": "change",
"realm_domain":
{
"domain": "zulip.org",
"allow_subdomains": true,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the set of
[allowed domains for new users](/help/restrict-account-creation#configuring-email-domain-restrictions)
has changed.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_domains
op:
type: string
enum:
- remove
domain:
type: string
description: |
The domain to be removed.
example:
{
"type": "realm_domains",
"op": "remove",
"domain": "zulip.org",
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to the user who requested a [data export](/help/export-your-organization)
when the status of the export changes.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_export
exports:
type: array
description: |
An array of dictionaries where each dictionary contains
data about a single organization export request.
items:
$ref: "#/components/schemas/RealmExport"
example:
{
"type": "realm_export",
"exports":
[
{
"id": 107,
"export_time": 1594825443.6567969322,
"acting_user_id": 10,
"export_url": null,
"deleted_timestamp": null,
"failed_timestamp": 1594825444.4363360405,
"pending": false,
},
],
"id": 1,
}
- type: object
additionalProperties: false
description: |
Event sent to users who can administer a newly created bot
user. Clients will also receive a `realm_user` event that
contains basic details (but not the API key).
The `realm_user` events are sufficient for clients that
only need to interact with the bot; this `realm_bot` event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- add
bot:
$ref: "#/components/schemas/Bot"
example:
{
"type": "realm_bot",
"op": "add",
"bot":
{
"email": "test-bot@zulip.testserver",
"user_id": 36,
"full_name": "Foo Bot",
"bot_type": 1,
"is_active": true,
"api_key": "6hc6MC9mpNFvoo0gSOWnZEq4aJEn8UNK",
"default_sending_stream": null,
"default_events_register_stream": null,
"default_all_public_streams": false,
"avatar_url": "https://secure.gravatar.com/avatar/af8abc2537d283b212a6bd4d1289956d?d=identicon&version=1",
"services": [],
"owner_id": 10,
},
"id": 1,
}
- type: object
description: |
Event sent to users who can administer a bot user when the bot is
configured. Clients may also receive a `realm_user` event that
for changes in public data about the bot (name, etc.).
The `realm_user` events are sufficient for clients that
only need to interact with the bot; this `realm_bot` event
type is relevant only for administering bots.
Only organization administrators and the user who owns the bot will
receive this event.
additionalProperties: false
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- update
bot:
allOf:
- description: |
Object containing details about the changed bot.
It contains two properties: the user id of the bot and
the property to be changed. The changed property is one
of the remaining properties listed below.
- $ref: "#/components/schemas/BasicBot"
example:
{
"type": "realm_bot",
"op": "update",
"bot":
{
"user_id": 37,
"services":
[
{
"base_url": "http://hostname.domain2.com",
"interface": 2,
"token": "grr8I2APXRmVL0FRTMRYAE4DRPQ5Wlaw",
},
],
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a bot has been deactivated.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- remove
bot:
type: object
description: |
Object containing details about the deactivated bot.
additionalProperties: false
properties:
user_id:
type: integer
description: |
The user ID of the deactivated bot.
full_name:
type: string
description: |
The full name of the deactivated bot.
example:
{
"type": "realm_bot",
"op": "remove",
"bot":
{"user_id": 35, "full_name": "Foo Bot"},
"id": 1,
}
- type: object
additionalProperties: false
description: |
Event sent to all users when a bot has been deactivated.
Note that this is very similar to the bot_remove event
and one of them will be removed soon.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_bot
op:
type: string
enum:
- delete
bot:
type: object
description: |
Object containing details about the deactivated bot.
additionalProperties: false
properties:
user_id:
type: integer
description: |
The user ID of the deactivated bot.
example:
{
"type": "realm_bot",
"op": "delete",
"bot":
{"user_id": 35, "full_name": "Foo Bot"},
"id": 1,
}
- type: object
additionalProperties: false
description: |
The simpler of two possible event types sent to all users
in a Zulip organization when the configuration of the
organization (realm) has changed.
Often individual settings are migrated from this format to
the [realm/update_dict](#realm-update_dict) event format when additional realm
settings are added whose values are coupled to each other
in some way. The specific values supported by this event
type are documented in the [realm/update_dict](#realm-update_dict)
documentation.
A correct client implementation should convert these
events into the corresponding [realm/update_dict](#realm-update_dict)
event and then process that.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- update
property:
type: string
description: |
The name of the property that was changed.
value:
description: |
The new value of the property.
oneOf:
- type: string
- type: boolean
- type: integer
extra_data:
description: |
Object containing extra data related to the changed
property.
type: object
additionalProperties: false
properties:
upload_quota:
type: integer
description: |
Note: Only present if changed property is `plan_type`.
The new upload quota for the Zulip organization.
example:
{
"type": "realm",
"op": "update",
"property": "disallow_disposable_email_addresses",
"value": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
organization (realm) is deactivated. Its main purpose is to
flush active longpolling connections so clients can immediately
show the organization as deactivated.
Clients cannot rely on receiving this event, because they will
no longer be able to authenticate to the Zulip API due to the
deactivation, and thus can miss it if they did not have an active
longpolling connection at the moment of deactivation.
Correct handling of realm deactivations requires that clients
parse authentication errors from GET /events; if that is done
correctly, the client can ignore this event type and rely on its
handling of the `GET /events` request it will do immediately
after processing this batch of events.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- deactivated
realm_id:
type: integer
description: |
The ID of the deactivated realm.
example:
{
"type": "realm",
"op": "deactivated",
"realm_id": 2,
"id": 0,
}
- type: object
description: |
Event sent to all the users whenever the Zulip server restarts.
Specifically, this event is sent whenever the Tornado process
for the user is restarted; in particular, this will always happen
when the Zulip server is upgraded.
Clients can use this event to know when they should get a new
event queue after a server upgrade. Clients doing so must implement
a random delay strategy to spread such restarts over 10 minutes or
more to avoid creating a synchronized thundering herd effect.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- restart
zulip_version:
type: string
description: |
The Zulip version number, in the format where this appears
in the [server_settings](/api/get-server-settings) and
[register](/api/register-queue) responses.
**Changes**: New in Zulip 4.0 (feature level 59).
zulip_merge_base:
type: string
description: |
The Zulip merge base number, in the format where this appears
in the [server_settings](/api/get-server-settings) and
[register](/api/register-queue) responses.
**Changes**: New in Zulip 5.0 (feature level 88).
zulip_feature_level:
type: integer
description: |
The [Zulip feature level](/api/changelog) of the server
after the restart.
Clients can safely avoid refetching their state and
creating a new event queue when the API feature level has not
changed, or when they know the specific feature level change
is not relevant to the client (E.g. it just adds a new endpoint
that the client doesn't use).
**Changes**: New in Zulip 4.0 (feature level 59).
immediate:
type: boolean
description: |
Whether the client should fetch a new event queue immediately,
rather than using a backoff strategy to avoid thundering herds.
A Zulip development server uses this parameter to reload
clients immediately.
server_generation:
type: integer
description: |
The timestamp at which the server started.
additionalProperties: false
example:
{
"id": 0,
"immediate": True,
"server_generation": 1619334181,
"type": "restart",
"zulip_feature_level": 57,
"zulip_version": "5.0-dev-1650-gc3fd37755f",
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
}
- type: object
additionalProperties: false
description: |
The more general of two event types that may be used when
sending an event to all users in a Zulip organization when
the configuration of the organization (realm) has changed.
Unlike the simpler [realm/update](#realm-update) event format, this
event type supports multiple properties being changed in a
single event.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm
op:
type: string
enum:
- update_dict
property:
type: string
deprecated: true
description: |
Always `"default"`. Present for backwards-compatibility with older
clients that predate the `update_dict` event style.
**Deprecated** and will be removed in a future release.
data:
type: object
description: |
An object containing the properties that have changed.
properties:
add_custom_emoji_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add custom emoji in this organization.
allow_edit_history:
type: boolean
description: |
Whether this organization is configured to allow users to access
[message edit history](/help/view-a-messages-edit-history).
allow_message_editing:
type: boolean
description: |
Whether this organizations [message edit policy](/help/configure-message-editing-and-deletion)
allows editing the content of messages.
authentication_methods:
type: object
additionalProperties:
description: |
Boolean describing whether the authentication method (i.e its key)
is enabled in this organization.
type: boolean
description: |
Dictionary of 'authentication_method_name': 'boolean' with each
entry describing whether the authentication name can be used for
authenticating into the organization.
bot_creation_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create bot users in this organization.
community_topic_editing_limit_seconds:
type: integer
description: |
Messages sent more than this many seconds ago cannot have
their topics edited by other users with this organization's
[message edit policy](/help/configure-message-editing-and-deletion).
**Changes**: New in Zulip 3.0 (feature level 11). Previously this
value was hardcoded to 86400 seconds (1 day).
create_public_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create public streams in this organization.
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `create_stream_policy` setting.
create_private_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create private streams in this organization.
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `create_stream_policy` setting.
default_code_block_language:
type: string
nullable: true
description: |
The default pygments language code to be used for a code blocks
in this organization. Null if no default has been set.
default_language:
type: string
description: |
The default language for the organization.
description:
type: string
description: |
The description of the organization, used on login and registration pages.
digest_emails_enabled:
type: boolean
description: |
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
digest_weekday:
type: integer
description: |
The day of the week when the organization will send
its weekly digest email to inactive users.
disallow_disposable_email_addresses:
type: boolean
description: |
Whether the organization disallows disposable email
addresses.
edit_topic_policy:
type: integer
description: |
The [policy][permission-level] for which users can edit topics of any message.
- 1 = members only
- 2 = admins only
- 3 = [full members][calc-full-member] only
- 4 = moderators only
- 5 = everyone
**Changes**: New in Zulip 5.0 (feature level 75), replacing the
previous `allow_community_topic_editing` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
email_address_visibility:
type: integer
description: |
The [policy][permission-level] for which users in this organization can see
the real email addresses of other users.
- 1 = everyone
- 2 = members only
- 3 = administrators only
- 4 = nobody (though note that administrators can change this setting).
- 5 = moderators only
[permission-level]: /api/roles-and-permissions#permission-levels
email_changes_disabled:
type: boolean
description: |
Whether users are allowed to change their own email address in this
organization. This is typically disabled for organizations that
synchronize accounts from LDAP or a similar corporate database.
emails_restricted_to_domains:
type: boolean
description: |
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
this organization are required to have an email
address in one of the `realm_domains` configured for the organization.
enable_spectator_access:
type: boolean
description: |
Whether web-public streams are enabled in this organization.
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
[server setting][server-settings] is enabled on the Zulip
server. See also the `create_web_public_stream_policy` realm
setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 109).
giphy_rating:
type: integer
description: |
Maximum rating of the GIFs that will be retrieved from GIPHY.
**Changes**: New in Zulip 4.0 (feature level 55).
icon_source:
type: string
description: |
String indicating whether the organization's
[profile icon](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the organization's icon.
- "G" means generated by Gravatar (the default).
- "U" means uploaded by an organization administrator.
icon_url:
type: string
description: |
The URL of the organization's [profile icon](/help/create-your-organization-profile).
inline_image_preview:
type: boolean
description: |
Whether this organization has been configured to enable
[previews of linked images](/help/allow-image-link-previews).
inline_url_embed_preview:
type: boolean
description: |
Whether this organization has been configured to enable
[previews of linked websites](/help/allow-image-link-previews).
invite_required:
type: boolean
description: |
Whether an invitation is required to join this organization.
invite_to_realm_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can invite other users to join the organization.
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
previous `invite_by_admins_only` boolean.
invite_to_stream_policy:
type: integer
description: |
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add other users to streams in this organization.
logo_source:
type: string
description: |
String indicating whether the organization's
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
logo_url:
type: string
description: |
The URL of the organization's wide logo configured in the
[organization profile](/help/create-your-organization-profile).
mandatory_topics:
type: boolean
description: |
Whether [topics are required](/help/require-topics) for messages in this organization.
message_content_allowed_in_email_notifications:
type: boolean
description: |
Whether notification emails in this organization are allowed to
contain Zulip the message content, or simply indicate that a new
message was sent.
message_content_delete_limit_seconds:
type: integer
nullable: true
description: |
Messages sent more than this many seconds ago cannot be deleted
with this organization's
[message deletion policy](/help/configure-message-editing-and-deletion).
Will not be 0. A 'null' value means no limit: messages can be deleted
regardless of how long ago they were sent.
**Changes**: No limit was represented using the
special value `0` before Zulip 5.0 (feature level 100).
message_content_edit_limit_seconds:
type: integer
description: |
Messages sent more than this many seconds ago cannot be edited
with this organization's
[message edit policy](/help/configure-message-editing-and-deletion).
move_messages_between_streams_policy:
type: integer
description: |
The [policy][permission-level] for which users can move messages from
one stream to another.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
**Changes**: New in Zulip 4.0 (feature level 56)
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
name:
type: string
description: |
The name of the organization, used in login pages etc.
name_changes_disabled:
type: boolean
description: |
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their name
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
night_logo_source:
type: string
description: |
String indicating whether the organization's dark theme
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
night_logo_url:
type: string
description: |
The URL of the organization's dark theme wide-format logo configured in the
[organization profile](/help/create-your-organization-profile).
notifications_stream_id:
type: integer
description: |
The ID of the stream to which notifications announcing the
creation of new streams are sent. -1 if such notifications are disabled.
Since these notifications are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
org_type:
type: integer
description: |
The [organization type](/help/organization-type)
for the realm.
- 0 = Unspecified
- 10 = Business
- 20 = Open-source project
- 30 = Education (non-profit)
- 35 = Education (for-profit)
- 40 = Research
- 50 = Event or conference
- 60 = Non-profit (registered)
- 70 = Government
- 80 = Political group
- 90 = Community
- 100 = Personal
- 1000 = Other
**Changes**: New in Zulip 6.0 (feature level 128).
plan_type:
type: integer
description: |
The plan type of the organization.
- 1 = Self-hosted organization (SELF_HOSTED)
- 2 = Zulip Cloud free plan (LIMITED)
- 3 = Zulip Cloud Standard plan (STANDARD)
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
presence_disabled:
type: boolean
description: |
Whether online presence of other users is shown in this
organization.
private_message_policy:
type: integer
description: |
[Policy](/api/roles-and-permissions#permission-levels)
for [who can send private messages](/help/restrict-private-messages)
in this organization.
- 1 = Everyone
- 2 = Nobody
send_welcome_emails:
type: boolean
description: |
Whether or not this organization is configured to send the standard Zulip
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
signup_notifications_stream_id:
type: integer
description: |
The ID of the stream to which notifications announcing
that new users have joined the organization are sent.
-1 if such notifications are disabled.
Since these notifications are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
user_group_edit_policy:
type: integer
description: |
The organization's [policy][permission-level] for
[who can manage user groups][user-group-permissions].
- 1 = All members can create and edit user groups
- 2 = Only organization administrators can create and edit user groups
- 3 = Only [full members][calc-full-member] can create and edit user groups
- 4 = Only organization administrators and moderators can create and edit user groups
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
video_chat_provider:
type: integer
description: |
The configured video call provider for the organization.
waiting_period_threshold:
type: integer
description: |
Members whose accounts have been created at least this many days ago
will be treated as [full members][calc-full-member]
for the purpose of settings that restrict access to new members.
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
want_advertise_in_communities_directory:
type: boolean
description: |
Whether the organization has given permission to be advertised in the
Zulip [communities directory](/help/communities-directory).
**Changes**: New in Zulip 6.0 (feature level 129).
wildcard_mention_policy:
type: integer
description: |
The [policy][permission-level] for who can use wildcard mentions in
large streams.
- 1 => Any user can use wildcard mentions in large streams.
- 2 => Only members can use wildcard mentions in large streams.
- 3 => Only [full members][calc-full-member] can use wildcard mentions in large streams.
- 4 => Only stream and organization administrators can use wildcard mentions in large streams.
- 5 => Only organization administrators can use wildcard mentions in large streams.
- 6 => Nobody can use wildcard mentions in large streams.
- 7 => Only organization administrators and moderators can use wildcard mentions in large streams.
All users will receive a warning/reminder when using
mentions in large streams, even when permitted to do so.
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
Zulip 4.0 (feature level 62).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
additionalProperties: false
example:
{
"type": "realm",
"op": "update_dict",
"property": "default",
"data":
{
"allow_message_editing": false,
"message_content_edit_limit_seconds": 0,
"edit_topic_policy": 2,
},
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event sent to all users in a Zulip organization when the
[default settings for new users][new-user-defaults]
of the organization (realm) have changed.
[new-user-defaults]: /help/configure-default-new-user-settings
See [PATCH /realm/user_settings_defaults](/api/update-realm-user-settings-defaults)
for details on possible properties.
**Changes**: New in Zulip 5.0 (feature level 95).
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- realm_user_settings_defaults
op:
type: string
enum:
- update
property:
type: string
description: |
The name of the property that was changed.
value:
description: |
The new value of the property.
oneOf:
- type: boolean
- type: integer
- type: string
example:
{
"type": "realm_user_settings_defaults",
"op": "update",
"property": "left_side_userlist",
"value": false,
"id": 0,
}
- type: object
additionalProperties: false
description: |
Event containing details of newly created drafts.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- add
drafts:
type: array
description: |
An array containing objects for the newly created drafts.
items:
$ref: "#/components/schemas/Draft"
example:
{
"type": "drafts",
"op": "add",
"drafts":
[
{
"id": 17,
"type": "private",
"to": [6],
"topic": "",
"content": "Hello there!",
"timestamp": 15954790200,
},
],
}
- type: object
additionalProperties: false
description: |
Event containing details for an edited draft.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- update
draft:
$ref: "#/components/schemas/Draft"
example:
{
"type": "drafts",
"op": "update",
"draft":
{
"id": 17,
"type": "private",
"to": [6, 7, 8, 9, 10],
"topic": "",
"content": "Hello everyone!",
"timestamp": 15954790200,
},
}
- type: object
additionalProperties: false
description: |
Event containing the id of a deleted draft.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
type:
allOf:
- $ref: "#/components/schemas/EventTypeSchema"
- enum:
- drafts
op:
type: string
enum:
- remove
draft_id:
type: integer
description: |
The ID of the draft that was just deleted.
example:
{
"type": "drafts",
"op": "update",
"draft_id": 17,
}
queue_id:
type: string
description: |
The ID of the registered queue.
example:
{
"queue_id": "1375801870:2942",
"events":
[
{
"id": 0,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "I come not, friends, to steal away your hearts.",
"content_type": "text/x-markdown",
"display_recipient": "Denmark",
"id": 12345678,
"recipient_id": 12314,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"topic_links": [],
"timestamp": 1375978403,
"type": "stream",
},
"type": "message",
},
{
"id": 1,
"message":
{
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "With mirth and laughter let old wrinkles come.",
"content_type": "text/x-markdown",
"display_recipient":
[
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572,
},
],
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"subject": "",
"topic_links": [],
"timestamp": 1375978404,
"type": "private",
},
"type": "message",
},
],
"msg": "",
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/BadEventQueueIdError"
- description: |
#### BAD_EVENT_QUEUE_ID errors
This error occurs if the target event queue has been garbage collected.
A compliant client will handle this error by re-initializing itself
(e.g. a Zulip web app browser window will reload in this case).
See [the /register endpoint docs](/api/register-queue) for details on how to
handle these correctly.
The following is the error response in such case:
delete:
operationId: delete-queue
summary: Delete an event queue
tags: ["real_time_events"]
description: |
Delete a previously registered queue.
`DELETE {{ api_url }}/v1/events`
parameters:
- $ref: "#/components/parameters/QueueId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/BadEventQueueIdError"
- description: |
A typical JSON response for when the `queue_id` is non-existent or the
associated queue has already been deleted:
/get_stream_id:
get:
operationId: get-stream-id
summary: Get stream ID
tags: ["streams"]
description: |
Get the unique ID of a given stream.
`GET {{ api_url }}/v1/get_stream_id`
parameters:
- name: stream
in: query
description: |
The name of the stream to access.
schema:
type: string
example: Denmark
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
stream_id:
type: integer
description: |
The ID of the given stream.
example: {"msg": "", "result": "success", "stream_id": 15}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
"result": "error",
}
description: |
An example JSON response for when the supplied stream does not exist:
/mark_all_as_read:
post:
operationId: mark-all-as-read
summary: Mark all messages as read
tags: ["messages"]
description: |
Marks all of the current user's unread messages as read.
`POST {{ api_url }}/v1/mark_all_as_read`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/mark_stream_as_read:
post:
operationId: mark-stream-as-read
summary: Mark messages in a stream as read
tags: ["messages"]
description: |
Mark all the unread messages in a stream as read.
parameters:
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 43
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/mark_topic_as_read:
post:
operationId: mark-topic-as-read
summary: Mark messages in a topic as read
tags: ["messages"]
description: |
Mark all the unread messages in a topic as read.
parameters:
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 43
required: true
- name: topic_name
in: query
description: |
The name of the topic whose messages should be marked as read.
schema:
type: string
example: new coffee machine
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/attachments:
get:
operationId: get-attachments
summary: Get attachments
tags: ["users"]
description: |
Fetch metadata on files uploaded by the requesting user.
`GET {{ api_url }}/v1/attachments`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
attachments:
type: array
description: |
A list of `attachment` objects, each containing
details about a file uploaded by the user.
items:
$ref: "#/components/schemas/Attachments"
upload_space_used:
type: integer
description: |
The total size of all files uploaded by in the organization,
in bytes.
example:
{
"result": "success",
"msg": "",
"attachments":
[
{
"id": 1,
"name": "166050.jpg",
"path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg",
"size": 571946,
"create_time": 1588145417000,
"messages":
[
{"id": 102, "date_sent": 1588145424000},
{"id": 103, "date_sent": 1588145448000},
],
},
],
"upload_space_used": 571946,
}
/attachments/{attachment_id}:
delete:
operationId: remove-attachment
summary: Delete an attachment
tags: ["users"]
description: |
Delete an uploaded file given its attachment ID.
Note that uploaded files that have been referenced in at least
one message are automatically deleted once the last message
containing a link to them is deleted (whether directly or via
a [message retention policy](/help/message-retention-policy)).
Uploaded files that are never used in a message are
automatically deleted a few weeks after being uploaded.
Attachment IDs can be contained from [GET /attachments](/api/get-attachments).
parameters:
- name: attachment_id
in: path
description: |
The ID of the attachment to be deleted.
schema:
type: string
example: "1"
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid attachment",
"code": "BAD_REQUEST",
}
description: |
A typical failed JSON response for when the `attachment_id` is invalid
"401":
description: Error.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"result": "error",
"msg": "Not logged in: API authentication or user session required",
}
description: |
A typical failed JSON response for when the user is not logged in
/drafts:
get:
operationId: get-drafts
tags: ["drafts"]
summary: Get drafts
description: |
Fetch all drafts for the current user.
`GET {{ api_url }}/v1/drafts`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
count:
type: integer
description: |
The number of drafts the user currently has. Also the
number of drafts returned under "drafts".
example: 3
drafts:
type: array
description: |
Returns all of the current user's drafts, in order of last edit time
(with the most recently edited draft appearing first).
items:
$ref: "#/components/schemas/Draft"
example:
{
"result": "success",
"msg": "",
"count": 3,
"drafts":
[
{
"id": 1,
"type": "stream",
"to": [3],
"topic": "sync drafts",
"content": "Let's add backend support for syncing drafts.",
"timestamp": 1595479019.43915,
},
{
"id": 2,
"type": "private",
"to": [4],
"topic": "",
"content": "What if we made it possible to sync drafts in Zulip?",
"timestamp": 1595479020.43916,
},
{
"id": 3,
"type": "private",
"to": [4, 10],
"topic": "",
"content": "What if we made it possible to sync drafts in Zulip?",
"timestamp": 1595479021.43916,
},
],
}
post:
operationId: create-drafts
tags: ["drafts"]
summary: Create drafts
description: |
Create one or more drafts on the server. These drafts will be automatically
synchronized to other clients via `drafts` events.
`POST {{ api_url }}/v1/drafts`
parameters:
- name: drafts
in: query
description: |
A JSON-encoded list of containing new draft objects.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Draft"
example:
[
{
"type": "stream",
"to": [1],
"topic": "questions",
"content": "What are the contribution guidelines for this project?",
"timestamp": 1595479019,
},
]
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
description: |
When all of the drafts in the request are valid, this endpoint will return
an array of the IDs for the drafts that were just created in the same
order as they were requested. If any of the drafts failed the validation
step, then none of the drafts will be created and we would not get this
status code. The typical JSON response in such a case is:
properties:
result: {}
msg: {}
ids:
type: array
description: |
An array of the IDs for the drafts that were just created in the same
order as they were submitted.
items:
type: integer
example: {"result": "success", "msg": "", "ids": [1, 2, 3]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
JSON response for when a draft targeted towards a stream does not specify
exactly one stream ID:
example:
{
"code": "BAD_REQUEST",
"msg": "Must specify exactly 1 stream ID for stream messages",
"result": "error",
}
/drafts/{draft_id}:
patch:
operationId: edit-draft
tags: ["drafts"]
summary: Edit a draft
description: |
Edit a draft on the server. The edit will be automatically
synchronized to other clients via `drafts` events.
`PATCH {{ api_url }}/v1/drafts/{draft_id}`
parameters:
- name: draft_id
in: path
schema:
type: integer
description: |
The ID of the draft to be edited.
required: True
example: 2
- name: draft
in: query
content:
application/json:
schema:
$ref: "#/components/schemas/Draft"
example:
{
"type": "stream",
"to": [1],
"topic": "questions",
"content": "how tough is a Lamy Safari?",
"timestamp": 1595479019,
}
description: |
A JSON-encoded object containing a replacement draft object for this ID.
required: True
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- description: |
JSON response for when no draft exists with the provided ID.
example: {"result": "error", "msg": "Draft does not exist"}
delete:
operationId: delete-draft
tags: ["drafts"]
summary: Delete a draft
description: |
Delete a single draft from the server. The deletion will be automatically
synchronized to other clients via a `drafts` event.
`DELETE {{ api_url }}/v1/drafts/{draft_id}`
parameters:
- name: draft_id
in: path
schema:
type: integer
description: |
The ID of the draft you want to delete.
required: True
example: 1
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"404":
description: Not Found.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- description: |
JSON response for when no draft exists with the provided ID.
example: {"result": "error", "msg": "Draft does not exist"}
/messages:
get:
operationId: get-messages
summary: Get messages
tags: ["messages"]
description: |
Fetch message history from a Zulip server.
`GET {{ api_url }}/v1/messages`
This `GET /api/v1/messages` endpoint is the primary way to fetch
message history from a Zulip server. It is useful both for Zulip
clients (e.g. the web, desktop, mobile, and terminal clients) as well
as bots, API clients, backup scripts, etc.
By specifying a [narrow filter](/api/construct-narrow), you can use
this endpoint to fetch the messages matching any search query that is
supported by Zulip's powerful full-text search backend.
When a narrow is not specified, it can be used to fetch a user's
message history. (We recommend paginating to 1000 messages at a time.)
In either case, you specify an `anchor` message (or ask the server to
calculate the first unread message for you and use that as the
anchor), as well as a number of messages before and after the anchor
message. The server returns those messages, sorted by message ID, as
well as some metadata that makes it easy for a client to determine
whether there are more messages matching the query that were not
returned due to the `num_before` and `num_after` limits.
We recommend using `num_before <= 1000` and `num_after <= 1000` to
avoid generating very large HTTP responses. A maximum of 5000 messages
can be obtained per request; attempting to exceed this will result in an
error.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- client_gravatar
- apply_markdown
- use_first_unread_anchor
parameters:
- name: anchor
in: query
description: |
Integer message ID to anchor fetching of new messages. Supports special
string values for when the client wants the server to compute the anchor
to use:
- `newest`: The most recent message.
- `oldest`: The oldest message.
- `first_unread`: The oldest unread message matching the
query, if any; otherwise, the most recent message.
The special values of `'newest'` and `'oldest'` are also supported
for anchoring the query at the most recent or oldest messages.
**Changes**: String values are new in Zulip 3.0 (feature level 1). The
`first_unread` functionality was supported in Zulip 2.1.x
and older by not sending anchor and using use_first_unread_anchor.
In Zulip 2.1.x and older, `oldest` can be emulated with
`anchor=0`, and `newest` with `anchor=10000000000000000`
(that specific large value works around a bug in Zulip
2.1.x and older in the `found_newest` return value).
schema:
oneOf:
- type: string
- type: integer
example: 43
- name: num_before
in: query
description: |
The number of messages with IDs less than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 4
required: true
- name: num_after
in: query
description: |
The number of messages with IDs greater than the anchor to retrieve.
schema:
type: integer
minimum: 0
example: 8
required: true
- name: narrow
in: query
description: |
The narrow where you want to fetch the messages from. See how to
[construct a narrow](/api/construct-narrow).
content:
application/json:
schema:
type: array
items:
type: object
default: []
example: [{"operand": "Denmark", "operator": "stream"}]
- $ref: "#/components/parameters/ClientGravatar"
- name: apply_markdown
in: query
description: |
If `true`, message content is returned in the rendered HTML
format. If `false`, message content is returned in the raw
Markdown-format text that user entered.
schema:
type: boolean
default: true
example: false
- name: use_first_unread_anchor
in: query
deprecated: true
description: |
Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older.
Whether to use the (computed by the server) first unread message
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
**Changes**: Deprecated in Zulip 3.0, replaced by
`anchor="first_unread"` instead.
schema:
type: boolean
default: false
example: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
description: |
When a request is successful, this endpoint returns a dictionary
containing the following (in addition to the `msg` and `result` keys
present in all Zulip API responses).
A typical successful JSON response may look like:
properties:
result: {}
msg: {}
anchor:
type: integer
description: |
The same `anchor` specified in the request (or the computed one, if
`use_first_unread_anchor` is `true`).
found_newest:
type: boolean
description: |
Whether the `messages` list includes the very newest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_oldest:
type: boolean
description: |
Whether the `messages` list includes the very oldest messages matching
the narrow (used by clients that paginate their requests to decide
whether there are more messages to fetch).
found_anchor:
type: boolean
description: |
Whether the anchor message is included in the
response. If the message with the ID specified
in the request does not exist or did not match
the narrow, this will be false.
history_limited:
type: boolean
description: |
Whether the message history was limited due to
plan restrictions. This flag is set to `true`
only when the oldest messages(`found_oldest`)
matching the narrow is fetched.
messages:
type: array
description: |
An array of `message` objects, each containing the following
fields:
items:
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
match_content:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML content of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
match_subject:
type: string
description: |
Only present if keyword search was included among the narrow parameters.
HTML-escaped topic of a queried message that matches the narrow, with
`<span class="highlight">` elements wrapping the matches for the
search keywords.
example:
{
"anchor": 21,
"found_newest": true,
"found_anchor": true,
"result": "success",
"msg": "",
"messages":
[
{
"subject": "",
"sender_realm_str": "zulip",
"type": "private",
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
"flags": ["read"],
"id": 16,
"display_recipient":
[
{
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
},
{
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago",
},
{
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest",
},
],
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
{
"subject": "Verona3",
"stream_id": 5,
"sender_realm_str": "zulip",
"type": "stream",
"content": "<p>Wait, is this from the frontend js code or backend python code</p>",
"flags": ["read"],
"id": 21,
"display_recipient": "Verona",
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527939746,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 20,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
],
}
post:
operationId: send-message
summary: Send a message
tags: ["messages"]
description: |
Send a stream or a private message.
`POST {{ api_url }}/v1/messages`
parameters:
- name: type
in: query
description: |
The type of message to be sent. `private` for a private message and
`stream` for a stream message.
schema:
type: string
enum:
- private
- stream
example: private
required: true
- name: to
in: query
description: |
For stream messages, either the name or integer ID of the stream. For
private messages, either a list containing integer user IDs or a list
containing string email addresses.
**Changes**: Support for using user/stream IDs was added in Zulip 2.0.0.
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
required: true
- $ref: "#/components/parameters/RequiredContent"
- name: topic
in: query
description: |
The topic of the message. Only required for stream messages
(`type="stream"`), ignored otherwise.
Maximum length of 60 characters.
**Changes**: New in Zulip 2.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
schema:
type: string
example: Castle
- name: queue_id
in: query
schema:
type: string
description: |
For clients supporting
[local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo),
the [event queue](/api/register-queue)
ID for the client. If passed, `local_id` is required. If the message is
successfully sent, the server will include `local_id` in the `message` event
that the client with this `queue_id` will receive notifying it of the new message
via [`GET /events`](/api/get-events). This lets the client know unambiguously
that it should replace the locally echoed message, rather than adding this new
message (which would be correct if the user had sent the new message from another
device).
example: "1593114627:0"
- name: local_id
in: query
schema:
type: string
description: |
For clients supporting local echo, a unique string-format identifier
chosen freely by the client; the server will pass it back to the client without
inspecting it, as described in the `queue_id` description.
example: "100.01"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
id:
type: integer
description: |
The unique ID assigned to the sent message.
deliver_at:
type: string
description: |
Present for scheduled messages, encodes the time when the message will
be sent. Note that scheduled messages ("Send later") is a beta API and
may change before it's a finished feature.
example: "2020-06-24 11:19:54.337533+00:00"
example: {"msg": "", "id": 42, "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/NonExistingStreamError"
- description: |
A typical failed JSON response for when a stream message is sent to a stream
that does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error",
}
description: |
A typical failed JSON response for when a private message is sent to a user
that does not exist:
/messages/{message_id}/history:
get:
operationId: get-message-history
summary: Get a message's edit history
tags: ["messages"]
description: |
Fetch the message edit history of a previously edited message.
`GET {{ api_url }}/v1/messages/{message_id}/history`
Note that edit history may be disabled in some organizations; see the
[Zulip Help Center documentation on editing messages][edit-settings].
[edit-settings]: /help/view-a-messages-edit-history
parameters:
- $ref: "#/components/parameters/MessageId"
x-response-description: |
Please note that the original message's snapshot only contains the fields
`topic`, `content`, `rendered_content`, `timestamp` and `user_id`. This
snapshot will be the only one present if the message has never been edited.
Also note that each snapshot object will only contain additional data for the
modified fields for that particular edit (e.g. if only the topic or stream
was edited, `prev_content`, `prev_rendered_content`, and
`content_html_diff` will not appear).
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
message_history:
type: array
items:
type: object
additionalProperties: false
properties:
topic:
type: string
description: |
The topic of the message immediately
after this edit event.
prev_topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately
prior to this edit event.
stream:
type: integer
description: |
Only present if message's stream was edited.
The ID of the stream containing the message
immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
prev_stream:
type: integer
description: |
Only present if message's stream was edited.
The ID of the stream containing the message immediately
prior to this edit event.
content:
type: string
description: |
The raw Markdown content of the message
immediately after this edit event.
rendered_content:
type: string
description: |
The rendered HTML representation of `content`.
prev_content:
type: string
description: |
Only present if message's content was edited.
The raw Markdown content of the message immediately
prior to this edit event.
prev_rendered_content:
type: string
description: |
Only present if message's content was edited.
The rendered HTML representation of `prev_content`.
user_id:
type: integer
nullable: true
description: |
The ID of the user that made the edit.
Will be null only for edit history
events predating March 2017.
Clients can display edit history events where this
is null as modified by either the sender (for content
edits) or an unknown user (for topic edits).
content_html_diff:
type: string
description: |
Only present if message's content was edited.
An HTML diff between this version of the message
and the previous one.
timestamp:
type: integer
description: |
The UNIX timestamp for this edit.
description: |
A chronologically sorted, oldest to newest, array
of `snapshot` objects, each one with the values of
the message after the edit.
example:
{
"message_history":
[
{
"content": "Hello!",
"topic": "party at my houz",
"rendered_content": "<p>Hello!</p>",
"timestamp": 1530129122,
"user_id": 5,
},
{
"topic": "party at my house",
"content": "Howdy!",
"prev_content": "Hello!",
"rendered_content": "<p>Howdy!</p>",
"user_id": 5,
"prev_rendered_content": "<p>Hello!</p>",
"content_html_diff": '<div><p><span class="highlight_text_inserted">Howdy!</span></p> <p><span class="highlight_text_deleted">Hello!</span></p></div>',
"prev_topic": "party at my houz",
"timestamp": 1530129134,
},
],
"msg": "",
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist:
/messages/flags:
post:
operationId: update-message-flags
summary: Update personal message flags
tags: ["messages"]
description: |
Add or remove personal message flags like `read` and `starred`
on a collection of message IDs.
`POST {{ api_url }}/v1/messages/flags`
For updating the `read` flag on common collections of messages, see also
the
[special endpoints for marking message as read in bulk](/api/mark-all-as-read).
x-parameter-description: |
## Available flags
<div>
<table>
<thead>
<tr>
<th style="width:30%">Flag</th>
<th style="width:70%">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>read</code></td>
<td>
Whether the user has read the message. Messages
start out unread (except for messages the user
themself sent using a non-API client) and can
later be marked as read.
</td>
</tr>
<tr>
<td><code>starred</code></td>
<td>Whether the user has <a href="/help/star-a-message">starred this message</a>.</td>
</tr>
<tr>
<td><code>collapsed</code></td>
<td>Whether the user has <a href="/help/collapse-a-message">collapsed this message</a>.</td>
</tr>
<tr>
<td><code>mentioned</code></td>
<td>
Whether the current user
<a href="/help/mention-a-user-or-group">was mentioned</a>
by this message, either directly or via a user
group. Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a mention of the current user.
</td>
</tr>
<tr>
<td><code>wildcard_mentioned</code></td>
<td>
Whether this message contained
<a href="/help/mention-a-user-or-group#mention-everyone-on-a-stream">wildcard mention</a>
like @**all**. Cannot be changed by the user directly, but
can change if the message is edited to add/remove
a wildcard mention.
</td>
</tr>
<tr>
<td><code>has_alert_word</code></td>
<td>
Whether the message contains any of the current user's
<a href="/help/pm-mention-alert-notifications#alert-words">configured alert words</a>.
Cannot be changed by the user directly, but
can change if the message is edited to add/remove
one of the current user's alert words.
</td>
</tr>
<tr>
<td><code>historical</code></td>
<td>
True for messages that the user did not receive
at the time they were sent but later was added to
the user's history (E.g. because they starred or
reacted to a message sent to a public stream
before they subscribed to that stream). Cannot be
changed by the user directly.
</td>
</tr>
</tbody>
</table>
</div>
parameters:
- name: messages
in: query
description: |
An array containing the IDs of the target messages.
content:
application/json:
schema:
type: array
items:
type: integer
example: [4, 8, 15]
required: true
- name: op
in: query
description: |
Whether to `add` the flag or `remove` it.
schema:
type: string
enum:
- add
- remove
example: add
required: true
- name: flag
in: query
description: |
The flag that should be added/removed.
schema:
type: string
example: read
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
messages:
type: array
items:
type: integer
description: |
An array with the IDs of the modified messages.
example:
{"msg": "", "messages": [4, 18, 15], "result": "success"}
/messages/render:
post:
operationId: render-message
summary: Render message
tags: ["messages"]
description: |
Render a message to HTML.
`POST {{ api_url }}/v1/messages/render`
parameters:
- $ref: "#/components/parameters/RequiredContent"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
rendered:
type: string
description: |
The rendered HTML.
example:
{
"msg": "",
"rendered": "<p><strong>foo</strong></p>",
"result": "success",
}
/messages/{message_id}/reactions:
post:
operationId: add-reaction
summary: Add an emoji reaction
tags: ["messages"]
description: |
Add an [emoji reaction](/help/emoji-reactions) to a message.
`POST {{ api_url }}/v1/messages/{message_id}/reactions`
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- emoji_code
- reaction_type
parameters:
- $ref: "#/components/parameters/MessageId"
- name: emoji_name
in: query
description: |
The target emoji's human-readable name.
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
schema:
type: string
example: "octopus"
required: true
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/ReactionType"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid emoji code",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response for when the emoji code is invalid:
delete:
operationId: remove-reaction
summary: Remove an emoji reaction
tags: ["messages"]
description: |
Remove an [emoji reaction](/help/emoji-reactions) from a message.
`DELETE {{ api_url }}/v1/messages/{message_id}/reactions`
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- emoji_code
- reaction_type
parameters:
- $ref: "#/components/parameters/MessageId"
- name: emoji_name
in: query
description: |
The target emoji's human-readable name.
To find an emoji's name, hover over a message to reveal
three icons on the right, then click the smiley face icon.
Images of available reaction emojis appear. Hover over the
emoji you want, and note that emoji's text name.
schema:
type: string
example: "octopus"
required: false
- $ref: "#/components/parameters/EmojiCode"
- $ref: "#/components/parameters/ReactionType"
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid message(s)",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response for when the emoji code is invalid:
/messages/matches_narrow:
get:
operationId: check-messages-match-narrow
summary: Check if messages match a narrow
tags: ["messages"]
description: |
Check whether a set of messages match a [narrow](/api/construct-narrow).
`GET {{ api_url }}/v1/messages/matches_narrow`
For many common narrows (E.g. a topic), clients can write an
efficient client-side check to determine whether a
newly arrived message belongs in the view.
This endpoint is designed to allow clients to handle more complex narrows
for which the client does not (or in the case of full-text search,
cannot) implement this check.
The format of the `match_subject` and `match_content` objects is designed to match
those of `GET /messages`, so that a client can splice these fields into a
`message` object received from `GET /events` and end up with an extended message
object identical to how a `GET /messages` for the current narrow would have
returned the message.
parameters:
- name: msg_ids
in: query
description: List of IDs for the messages to check.
content:
application/json:
schema:
type: array
items:
type: integer
example: [31, 32]
required: true
- name: narrow
in: query
description:
A structure defining the narrow to check against. See how to
[construct a narrow](/api/construct-narrow).
content:
application/json:
schema:
type: array
items:
type: object
example: [{"operator": "has", "operand": "link"}]
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessDescription"
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
messages:
type: object
description: |
A dictionary with a key for each queried message that matches the narrow,
with message IDs as keys and search rendering data as values.
additionalProperties:
type: object
additionalProperties: false
properties:
match_content:
type: string
description: |
HTML content of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included, wrapping the matches for the search keywords.
match_subject:
type: string
description: |
HTML-escaped topic of a queried message that matches the narrow. If the
narrow is a search narrow, `<span class="highlight">` elements
will be included wrapping the matches for the search keywords.
description: |
`message_id`: The ID of the message that matches the narrow. No record will be returned
for queried messages that do not match the narrow.
example:
{
"result": "success",
"msg": "",
"messages":
{
"31":
{
"match_content": '<p><a href="http://foo.com" target="_blank" title="http://foo.com">http://foo.com</a></p>',
"match_subject": "test_topic",
},
},
}
/messages/{message_id}:
get:
operationId: get-message
summary: Fetch a single message.
tags: ["messages"]
description: |
Given a message ID, return the message object.
`GET {{ api_url }}/v1/messages/{msg_id}`
Additionally, a `raw_content` field is included. This field is
useful for clients that primarily work with HTML-rendered
messages but might need to occasionally fetch the message's
raw Markdown (e.g. for [view
source](/help/view-the-markdown-source-of-a-message) or
prefilling a message edit textarea).
**Changes**: Before Zulip 5.0 (feature level 120), this
endpoint only returned the `raw_content` field.
parameters:
- $ref: "#/components/parameters/MessageId"
- name: apply_markdown
in: query
description: |
If `true`, message content is returned in the rendered HTML
format. If `false`, message content is returned in the raw
Markdown-format text that user entered.
**Changes**: New in Zulip 5.0 (feature level 120).
schema:
type: boolean
default: true
example: false
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
raw_content:
type: string
deprecated: true
description: |
The raw Markdown content of the message.
**Deprecated** and to be removed once no longer required for
legacy clients. Modern clients should prefer passing
`apply_markdown=false` to request raw message content.
message:
description: |
An object containing details of the message.
**Changes**: New in Zulip 5.0 (feature level 120).
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
flags:
type: array
description: |
The user's [message flags][message-flags] for the message.
[message-flags]: /api/update-message-flags#available-flags
items:
type: string
example:
{
"raw_content": "**Don't** forget your towel!",
"result": "success",
"msg": "",
"message":
{
"subject": "",
"sender_realm_str": "zulip",
"type": "private",
"content": "<p>Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.</p>",
"flags": ["read"],
"id": 16,
"display_recipient":
[
{
"id": 4,
"is_mirror_dummy": false,
"email": "hamlet@zulip.com",
"full_name": "King Hamlet",
},
{
"id": 5,
"is_mirror_dummy": false,
"email": "iago@zulip.com",
"full_name": "Iago",
},
{
"id": 8,
"is_mirror_dummy": false,
"email": "prospero@zulip.com",
"full_name": "Prospero from The Tempest",
},
],
"content_type": "text/html",
"is_me_message": false,
"timestamp": 1527921326,
"sender_id": 4,
"sender_full_name": "King Hamlet",
"recipient_id": 27,
"topic_links": [],
"client": "populate_db",
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"submessages": [],
"sender_email": "hamlet@zulip.com",
"reactions": [],
},
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist or it
is not visible to the user making the query (e.g. it was a PM between other
two users):
patch:
operationId: update-message
summary: Edit a message
tags: ["messages"]
description: |
Edit/update the content or topic of a message.
`PATCH {{ api_url }}/v1/messages/{msg_id}`
`{msg_id}` in the above URL should be replaced with the ID of the
message you wish you update.
You can [resolve topics](/help/resolve-a-topic) by editing the
topic to `✔ {original_topic}`.
**Note**: See [configuring message
editing][config-message-editing] for detailed documentation on
when users are allowed to edit topics.
[config-message-editing]: /help/configure-message-editing-and-deletion
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- stream_id
parameters:
- $ref: "#/components/parameters/MessageId"
- name: topic
in: query
description: |
The topic to move the message(s) to, to request changing the topic.
Should only be sent when changing the topic, and will throw an error
if the target message is not a stream message.
Maximum length of 60 characters.
**Changes**: New in Zulip 2.0. Previous Zulip releases encoded
this as `subject`, which is currently a deprecated alias.
schema:
type: string
example: Castle
- name: propagate_mode
in: query
description: |
Which message(s) should be edited: just the one indicated in
`message_id`, messages in the same topic that had been sent after this
one, or all of them.
Only the default value of `change_one` is valid when
editing only the content of a message.
This parameter determines both which messages get moved and also whether
clients that are currently narrowed to the topic containing the message
should navigate or adjust their compose box recipient to point to the
post-edit stream/topic.
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
- name: send_notification_to_old_thread
in: query
description: |
Whether to send breadcrumb message to the old thread to
notify users where the messages were moved to.
**Changes**: New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: true
example: true
- name: send_notification_to_new_thread
in: query
description: |
Whether to send a notification message to the new thread to
notify users where the messages came from.
**Changes**: New in Zulip 3.0 (feature level 9).
schema:
type: boolean
default: true
example: true
- $ref: "#/components/parameters/OptionalContent"
- name: stream_id
in: query
description: |
The stream ID to move the message(s) to, to request moving
messages to another stream.
Should only be sent when changing the stream, and will throw an error
if the target message is not a stream message.
schema:
type: integer
example: 43
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- properties:
msg:
enum:
- Your organization has turned off message editing
- You don't have permission to edit this message
- The time limit for editing this message has past
- Nothing to change
- Topic can't be empty
example:
{
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
"result": "error",
}
description: |
A typical JSON response for when one doesn't have the permission to
edit a particular message:
delete:
operationId: delete-message
summary: Delete a message
tags: ["messages"]
description: |
Permanently delete a message.
`DELETE {{ api_url }}/v1/messages/{msg_id}`
This API corresponds to the
[delete a message completely][delete-completely] feature documented in
the Zulip Help Center.
[delete-completely]: /help/edit-or-delete-a-message#delete-a-message-completely
x-requires-administrator: true
parameters:
- $ref: "#/components/parameters/MessageId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/InvalidMessageError"
- description: |
An example JSON response for when the specified message does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- description: |
An example JSON response for when the user making the query does not
have permission to delete the message:
example:
{
"code": "BAD_REQUEST",
"msg": "You don't have permission to delete this message",
"result": "error",
}
/user_uploads:
post:
operationId: upload-file
summary: Upload a file
tags: ["messages"]
description: |
Upload a single file and get the corresponding URI.
`POST {{ api_url }}/v1/user_uploads`
Initially, only you will be able to access the link. To share the
uploaded file, you'll need to [send a message][send-message]
containing the resulting link. Users who can already access the link
can reshare it with other users by sending additional Zulip messages
containing the link.
[uploaded-files]: /help/manage-your-uploaded-files
[send-message]: /api/send-message
x-parameter-description: |
As described above, the 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_FILE_UPLOAD_SIZE`
in the [server's settings][1]. `MAX_FILE_UPLOAD_SIZE` defaults
to 25MB.
[1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
filename:
type: string
format: binary
example: /path/to/file
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
uri:
type: string
description: |
The URI of the uploaded file.
example:
{
"msg": "",
"result": "success",
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
}
/user_uploads/{realm_id_str}/{filename}:
get:
operationId: get-file-temporary-url
summary: Get public temporary URL
tags: ["messages"]
description: |
Get a temporary URL for access to the file that doesn't require authentication.
parameters:
- name: realm_id_str
in: path
description: |
The realm id.
schema:
type: integer
example: 1
required: true
- name: filename
in: path
description: |
Path to the URL.
schema:
type: string
example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
url:
type: string
description: |
A temporary URL that can be used to access the uploaded file
without Zulip's normal API authentication.
example:
{
"msg": "",
"result": "success",
"url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55",
}
/users:
get:
operationId: get-users
summary: Get all users
tags: ["users"]
description: |
Retrieve details on all users in the organization. Optionally
includes values of [custom profile field](/help/add-custom-profile-fields).
`GET {{ api_url }}/v1/users`
You can also [fetch details on a single user](/api/get-user).
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` query parameter as follows:
parameters:
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
members:
type: array
description: |
A list of `user` objects, each containing details about a user in the
organization.
items:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"members":
[
{
"is_active": true,
"email": "AARON@zulip.com",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
"bot_type": null,
"timezone": "",
"is_bot": false,
"user_id": 7,
"profile_data": {},
"is_guest": false,
"date_joined": "2019-10-20T07:50:53.728864+00:00",
"full_name": "aaron",
},
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "vim"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
},
{
"bot_owner_id": 11,
"is_guest": false,
"date_joined": "2019-10-20T12:52:17.862053+00:00",
"full_name": "Iago's Bot",
"email": "iago-bot@zulipdev.com",
"is_active": true,
"avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"user_id": 23,
"bot_type": 1,
"timezone": "",
"is_bot": true,
},
],
}
post:
operationId: create-user
summary: Create a user
tags: ["users"]
description: |
{!can-create-users-only.md!}
Create a new user account via the API.
`POST {{ api_url }}/v1/users`
x-requires-administrator: true
parameters:
- name: email
in: query
description: |
The email address of the new user.
schema:
type: string
example: username@example.com
required: true
- name: password
in: query
description: |
The password of the new user.
schema:
type: string
example: abcd1234
required: true
- name: full_name
in: query
description: |
The full name of the new user.
schema:
type: string
example: New User
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
user_id:
type: integer
description: |
The ID assigned to the newly created user.
**Changes**: New in Zulip 4.0 (feature level 30).
example: {"msg": "", "result": "success", "user_id": 25}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"msg": "Email 'newbie@zulip.com' already in use",
"result": "error",
}
description: |
A typical JSON response for when another user with the same
email address already exists in the realm:
/users/{user_id}/reactivate:
post:
operationId: reactivate-user
summary: Reactivate a user
tags: ["users"]
x-requires-administrator: true
description: |
[Reactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
`POST {{ api_url }}/v1/users/{user_id}/reactivate`
parameters:
- $ref: "#/components/parameters/UserId"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/SuccessDescription"
- $ref: "#/components/schemas/JsonSuccess"
- example: {"msg": "", "result": "success"}
/users/{user_id_or_email}/presence:
get:
operationId: get-user-presence
summary: Get user presence
tags: ["users"]
description: |
Get the presence status for a specific user.
This endpoint is most useful for embedding data about a user's
presence status in other sites (E.g. an employee directory). Full
Zulip clients like mobile/desktop apps will want to use the main
presence endpoint, which returns data for all active users in the
organization, instead.
`GET {{ api_url }}/v1/users/{user_id_or_email}/presence`
See
[Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html)
for details on the data model for presence in Zulip.
parameters:
- name: user_id_or_email
in: path
description: |
The user_id or Zulip display email address of the user whose presence you want to fetch.
**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported
identifying the user by Zulip display email.
schema:
type: string
example: iago@zulip.com
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
presence:
type: object
description: |
An object containing the presence details for every client the user has
logged into.
additionalProperties:
type: object
additionalProperties: false
properties:
timestamp:
type: integer
description: |
when this update was received; if the timestamp
is more than a few minutes in the past, the user is offline.
status:
type: string
description: |
either `active` or `idle`: whether the user had
recently interacted with Zulip at the time in the timestamp
(this distinguishes orange vs. green dots in the Zulip web
UI; orange/idle means we don't know whether the user is
actually at their computer or just left the Zulip app open
on their desktop).
description: |
`{client_name}` or `aggregated`: the keys for these objects are
the names of the different clients where this user is logged in,
like `website`, `ZulipDesktop`, `ZulipTerminal`, or
`ZulipMobile`. There is also an `aggregated` key, which matches
the contents of the object that has been updated most
recently. For most applications, you'll just want to look at the
`aggregated` key.
example:
{
"presence":
{
"website":
{"timestamp": 1532697622, "status": "active"},
"ZulipMobile":
{"timestamp": 1522687421, "status": "active"},
"aggregated":
{"timestamp": 1532697622, "status": "active"},
},
"result": "success",
"msg": "",
}
/users/me:
get:
operationId: get-own-user
summary: Get own user
tags: ["users"]
description: |
Get basic data about the user/bot that requests this endpoint.
`GET {{ api_url }}/v1/users/me`
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
avatar_url:
type: string
description: |
URL for the user's avatar.
**Changes**: New in Zulip 2.1.0.
example: "x"
avatar_version:
type: integer
description: |
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: 1
email:
type: string
description: |
Email of the requesting user.
example: "iago@zulip.com"
full_name:
type: string
description: |
Full name of the requesting user.
example: "Iago"
is_admin:
type: boolean
description: |
A boolean indicating if the requesting user is an admin.
example: true
is_owner:
type: boolean
description: |
A boolean indicating if the requesting user is
an organization owner.
**Changes**: New in Zulip 3.0 (feature level 8).
example: false
is_billing_admin:
type: boolean
description: |
A boolean indicating if the requesting user is
a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
example: false
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: |
[Organization-level role](/api/roles-and-permissions) of the user.
Possible values are:
- Organization owner => 100
- Organization administrator => 200
- Organization moderator => 300
- Member => 400
- Guest => 600
**Changes**: New in Zulip 4.0 (feature level 59).
is_guest:
type: boolean
description: |
A boolean indicating if the requesting user is a guest.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: false
is_bot:
type: boolean
description: |
A boolean indicating if the requesting user is a bot.
example: false
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: true
timezone:
type: string
description: |
The time zone of the user.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: ""
date_joined:
type: string
description: |
The time the user account was created.
**Changes**: New in Zulip 3.0 (feature level 10). Previous
versions do not return this field.
example: "2019-10-20T07:50:53.728864+00:00"
max_message_id:
type: integer
deprecated: true
description: |
The integer ID of the last message received by your account.
**Deprecated**. We plan to remove this in favor of recommending
using `GET /messages` with `anchor="newest"`.
example: 30
user_id:
type: integer
description: |
The user's ID.
example: 1
delivery_email:
type: string
description: |
The user's real email address. This field is present only if
[email address visibility](/help/restrict-visibility-of-email-addresses) is
limited and you are an administrator with access to real email addresses
under the configured policy.
profile_data:
$ref: "#/components/schemas/profile_data"
example:
{
"avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1",
"avatar_version": 1,
"email": "iago@zulip.com",
"full_name": "Iago",
"is_admin": true,
"is_owner": false,
"role": 200,
"is_guest": false,
"is_billing_admin": false,
"is_bot": false,
"is_active": true,
"timezone": "",
"date_joined": "2019-10-20T07:50:53.728864+00:00",
"max_message_id": 30,
"msg": "",
"result": "success",
"user_id": 5,
"profile_data":
{
"5": {"value": "2000-01-01"},
"4": {"value": "emacs"},
"7": {"value": "[10]"},
"1":
{
"value": "+1-234-567-8901",
"rendered_value": "<p>+1-234-567-8901</p>",
},
"2":
{
"rendered_value": "<p>Betrayer of Othello.</p>",
"value": "Betrayer of Othello.",
},
"8": {"value": "zulip"},
"3":
{
"value": "Apples",
"rendered_value": "<p>Apples</p>",
},
"6":
{
"value": "https://zulip.readthedocs.io/en/latest/",
},
},
}
delete:
operationId: deactivate-own-user
summary: Deactivate own user
tags: ["users"]
description: |
Deactivates the user's account. See also the administrative endpoint for
[deactivating another user](/api/deactivate-user).
`DELETE {{ api_url }}/v1/users/me`
This endpoint is primarily useful to Zulip clients providing a user settings UI.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"msg": "Cannot deactivate the only organization owner",
"result": "error",
}
description: |
An example JSON error response when attempting to deactivate the only
organization owner in an organization:
/users/me/status:
post:
operationId: update-status
summary: Update your status
tags: ["users"]
description: |
Change your [status](/help/status-and-availability).
`POST {{ api_url }}/v1/users/me/status`
A request to this endpoint will only change the parameters passed.
For example, passing just `status_text` requests a change in the status
text, but will leave the status emoji unchanged.
Clients that wish to set the user's status to a specific value should
pass all supported parameters.
**Changes**: In Zulip 5.0 (feature level 86), added support for
`emoji_name`, `emoji_code`, and `reaction_type` parameters.
parameters:
- name: status_text
schema:
type: string
allowEmptyValue: true
in: query
description: |
The text content of the status message. Sending the empty string
will clear the user's status.
**Note**: The limit on the size of the message is 60 characters.
example: on vacation
required: false
- name: away
schema:
type: boolean
in: query
description: |
Whether the user should be marked as "away".
example: true
required: false
- name: emoji_name
schema:
type: string
allowEmptyValue: true
in: query
description: |
The name for the emoji to associate with this status.
**Changes**: New in Zulip 5.0 (feature level 86).
example: car
required: false
- name: emoji_code
schema:
type: string
in: query
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
**Changes**: New in Zulip 5.0 (feature level 86).
example: 1f697
required: false
- name: reaction_type
schema:
type: string
in: query
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86).
example: unicode_emoji
required: false
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Client did not pass any new values.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when no changes were requested:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "status_text is too long (limit: 60 characters)",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the
`status_text` message exceeds the limit of
60 characters:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Client must pass emoji_name if they pass either emoji_code or reaction_type.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when `emoji_name` is not specified
but `emoji_code` or `reaction_type` is specified:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Emoji 'invalid' does not exist",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the emoji name does not exist:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid emoji name.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the emoji name is invalid:
- allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Invalid custom emoji.",
"code": "BAD_REQUEST",
}
description: |
An example JSON error response when the custom emoji is invalid:
/users/me/{stream_id}/topics:
get:
operationId: get-stream-topics
summary: Get topics in a stream
tags: ["streams"]
description: |
Get all the topics in a specific stream
`GET {{ api_url }}/v1/users/me/{stream_id}/topics`
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
topics:
type: array
description: |
An array of `topic` objects.
items:
type: object
additionalProperties: false
properties:
max_id:
description: |
The message ID of the last message sent to this topic.
type: integer
name:
description: |
The name of the topic.
type: string
example:
{
"msg": "",
"result": "success",
"topics":
[
{"max_id": 26, "name": "Denmark3"},
{"max_id": 23, "name": "Denmark1"},
{"max_id": 6, "name": "Denmark2"},
],
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error",
}
description: |
An example JSON response for when the user is attempting to fetch the topics
of a non-existing stream (or also a private stream they don't have access to):
/users/me/subscriptions:
get:
operationId: get-subscriptions
summary: Get subscribed streams
tags: ["streams"]
description: |
Get all streams that the user is subscribed to.
`GET {{ api_url }}/v1/users/me/subscriptions`
# operationId can be used to record which view function
# corresponds to an endpoint. TODO: Add these for more
# endpoints, and perhaps use this to provide links to implementations.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
description: |
You may pass the `include_subscribers` query parameter as follows:
parameters:
enum:
- ""
parameters:
- $ref: "#/components/parameters/IncludeSubscribers"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
# TODO: Is this the best way to declare required elements in 200 responses?
- required:
- subscriptions
additionalProperties: false
properties:
result: {}
msg: {}
subscriptions:
type: array
description: |
A list of dictionaries where each dictionary contains
information about one of the subscribed streams.
items:
$ref: "#/components/schemas/Subscriptions"
example:
{
"msg": "",
"result": "success",
"subscriptions":
[
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "A Scandinavian country",
"desktop_notifications": true,
"email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981",
"is_muted": false,
"invite_only": false,
"name": "Denmark",
"pin_to_top": false,
"push_notifications": false,
"role": 20,
"stream_id": 1,
"subscribers": [7, 10, 11, 12, 14],
},
{
"audible_notifications": true,
"color": "#e79ab5",
"description": "Located in the United Kingdom",
"desktop_notifications": true,
"email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981",
"is_muted": false,
"invite_only": false,
"name": "Scotland",
"pin_to_top": false,
"push_notifications": false,
"role": 50,
"stream_id": 3,
"subscribers": [7, 11, 12, 14],
},
],
}
post:
operationId: subscribe
summary: Subscribe to a stream
tags: ["streams"]
description: |
Subscribe one or more users to one or more streams.
`POST {{ api_url }}/v1/users/me/subscriptions`
If any of the specified streams do not exist, they are automatically
created. The initial [stream settings](/api/update-stream) will be determined
by the optional parameters like `invite_only` detailed below.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- subscriptions
- type: include
description: |
To subscribe another user to a stream, you may pass in
the `principals` parameter, like so:
parameters:
enum:
- subscriptions
- principals
parameters:
- name: subscriptions
in: query
description: |
A list of dictionaries containing the key `name` and value
specifying the name of the stream to subscribe. If the stream does not
exist a new stream is created. The description of the stream created can
be specified by setting the dictionary key `description` with an
appropriate value.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the stream.
description:
type: string
description: |
The [description](/help/change-the-stream-description)
to use for a new stream being created, in text/markdown format.
required:
- name
example:
no-description:
value: {"name": "Verona"}
with-description:
value: {"name": "Verona", "description": "Italian city"}
example: [{"name": "Verona", "description": "Italian city"}]
required: true
- $ref: "#/components/parameters/Principals"
- name: authorization_errors_fatal
in: query
description: |
A boolean specifying whether authorization errors (such as when the
requesting user is not authorized to access a private stream) should be
considered fatal or not. When `True`, an authorization error is reported
as such. When set to `False`, the response will be a 200 and any streams
where the request encountered an authorization error will be listed
in the `unauthorized` key.
schema:
type: boolean
default: true
example: false
- name: announce
in: query
description: |
If one of the streams specified did not exist previously and is thus created
by this call, this determines whether [notification bot](/help/configure-notification-bot)
will send an announcement about the new stream's creation.
schema:
type: boolean
default: false
example: true
- name: invite_only
in: query
description: |
As described above, this endpoint will create a new stream if passed
a stream name that doesn't already exist. This parameters and the ones
that follow are used to request an initial configuration of a created
stream; they are ignored for streams that already exist.
This parameter determines whether any newly created streams will be
private streams.
schema:
type: boolean
default: false
example: true
- name: is_web_public
in: query
description: |
This parameter determines whether any newly created streams will be
web-public streams.
Note that creating web-public streams requires the
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
to be enabled on the Zulip server in question, the organization
to have enabled the `enable_spectator_access` realm setting, and
the current use to have permission under the organization's
`create_web_public_stream_policy` realm setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 98).
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/MessageRetentionDays"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- $ref: "#/components/schemas/SuccessDescription"
- example:
{
"already_subscribed":
{"newbie@zulip.com": ["new stream"]},
"msg": "",
"result": "success",
"subscribed": {"iago@zulip.com": ["new stream"]},
}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error",
}
description: |
A typical response for when the requesting user does not have access to
a private stream and `authorization_errors_fatal` is `True`:
- allOf:
- $ref: "#/components/schemas/AddSubscriptionsResponse"
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": ["private_stream"],
}
description: |
A typical response for when the requesting user does not have access to
a private stream and `authorization_errors_fatal` is `False`:
patch:
operationId: update-subscriptions
summary: Update subscriptions
tags: ["streams"]
description: |
Update which streams you are subscribed to.
parameters:
- name: delete
in: query
description: |
A list of stream names to unsubscribe from.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Verona", "Denmark"]
required: false
- name: add
in: query
description: |
A list of objects describing which streams to subscribe to, optionally
including per-user subscription parameters (e.g. color) and if the
stream is to be created, its description.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
name:
type: string
color:
type: string
description:
type: string
example:
[
{"name": "Verona"},
{
"name": "Denmark",
"color": "#e79ab5",
"description": "A Scandinavian country",
},
]
required: false
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- required:
- subscribed
- already_subscribed
- removed
additionalProperties: false
properties:
result: {}
msg: {}
subscribed:
type: object
description: |
A dictionary where the key is the email
address of the user/bot and the value is a
list of the names of the streams that were
subscribed to as a result of the query.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams that
the user was subscribed to as a result of the query.
type: array
items:
type: string
already_subscribed:
type: object
description: |
A dictionary where the key is the email
address of the user/bot and the value is a
list of the names of the streams that the
user/bot is already subscribed to.
additionalProperties:
description: |
`{email_id}`: A list of the names of streams that
the user was already subscribed to.
type: array
items:
type: string
not_removed:
type: array
items:
type: string
description: |
A list of the names of streams that the user
is already unsubscribed from, and hence
doesn't need to be unsubscribed.
removed:
type: array
items:
type: string
description: |
A list of the names of streams which were unsubscribed
from as a result of the query.
example:
{
"msg": "",
"subscribed": {},
"already_subscribed": {"iago@zulip.com": ["Verona"]},
"not_removed": [],
"removed": ["new stream"],
"result": "success",
}
delete:
operationId: unsubscribe
summary: Unsubscribe from a stream
tags: ["streams"]
description: |
Unsubscribe yourself or other users from one or more streams.
`DELETE {{ api_url }}/v1/users/me/subscriptions`
x-curl-examples-parameters:
oneOf:
- type: include
description: |
**Note**: Unsubscribing another user from a stream requires
administrative privileges.
parameters:
enum:
- subscriptions
- type: exclude
parameters:
enum:
- ""
description: |
You may specify the `principals` parameter like so:
parameters:
- name: subscriptions
in: query
description: |
A list of stream names to unsubscribe from. This parameter is called
`streams` in our Python API.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Verona", "Denmark"]
required: true
- $ref: "#/components/parameters/Principals"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
not_removed:
type: array
items:
type: string
description: |
A list of the names of streams that the user is already unsubscribed
from, and hence doesn't need to be unsubscribed.
removed:
type: array
items:
type: string
description: |
A list of the names of streams which were unsubscribed from as a result
of the query.
example:
{
"msg": "",
"not_removed": [],
"removed": ["new stream"],
"result": "success",
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/NonExistingStreamError"
- description: |
A typical failed JSON response for when the target stream does not exist:
/users/me/subscriptions/muted_topics:
patch:
operationId: mute-topic
summary: Topic muting
tags: ["streams"]
description: |
This endpoint mutes/unmutes a topic within a stream that the current
user is subscribed to. Muted topics are displayed faded in the Zulip
UI, and are not included in the user's unread count totals.
`PATCH {{ api_url }}/v1/users/me/subscriptions/muted_topics`
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- stream_id
parameters:
- name: stream
in: query
description: |
The name of the stream to access.
schema:
type: string
example: Denmark
required: false
- name: stream_id
in: query
description: |
The ID of the stream to access.
schema:
type: integer
example: 43
required: false
- name: topic
in: query
description: |
The topic to (un)mute. Note that the request will succeed regardless of
whether any messages have been sent to the specified topic.
schema:
type: string
example: dinner
required: true
- name: op
in: query
description: |
Whether to mute (`add`) or unmute (`remove`) the provided topic.
schema:
type: string
enum:
- add
- remove
example: add
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{"msg": "Topic already muted", "result": "error"}
description: |
An example JSON response for when an `add` operation is requested for a topic
that has already been muted:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{"msg": "Topic is not muted", "result": "error"}
description: |
An example JSON response for when a `remove` operation is requested for a
topic that had not been previously muted:
/users/me/muted_users/{muted_user_id}:
post:
operationId: mute-user
summary: Mute a user
tags: ["users"]
description: |
This endpoint [mutes a user](/help/mute-a-user). Messages sent by users
you've muted will be automatically marked as read and hidden.
`POST {{ api_url }}/v1/users/me/muted_users/{muted_user_id}`
Muted users should be implemented by clients as follows:
- The server will immediately mark all messages sent by the muted
user as read. This will automatically clear any existing mobile
push notifications related to the muted user.
- The server will mark any new messages sent by the muted user as read
for your account, which prevents all email and mobile push notifications.
- Clients should exclude muted users from presence lists or other UI
for viewing or composing 1:1 private messages. 1:1 private messages sent by
muted users should be hidden everywhere in the Zulip UI.
- Stream messages and group private messages sent by the muted
user should avoid displaying the content and name/avatar,
but should display that N messages by a muted user were
hidden (so that it is possible to interpret the messages by
other users who are talking with the muted user).
- Group private message conversations including the muted user
should display muted users as "Muted user", rather than
showing their name, in lists of such conversations, along with using
a blank grey avatar where avatars are displayed.
- Administrative/settings UI elements for showing "All users that exist
on this stream or realm", e.g. for organization
administration or showing stream subscribers, should display
the user's name as normal.
**Changes**: New in Zulip 4.0 (feature level 48).
parameters:
- $ref: "#/components/parameters/MutedUserId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example: {"msg": "Cannot mute self", "result": "error"}
description: |
An example JSON response for when the user is yourself:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example: {"msg": "No such user", "result": "error"}
description: |
An example JSON response for when the user is nonexistent or inaccessible:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{"msg": "User already muted", "result": "error"}
description: |
An example JSON response for when the user is already muted:
delete:
operationId: unmute-user
summary: Unmute a user
tags: ["users"]
description: |
This endpoint unmutes a user.
`DELETE {{ api_url }}/v1/users/me/muted_users/{muted_user_id}`
**Changes**: New in Zulip 4.0 (feature level 48).
parameters:
- $ref: "#/components/parameters/MutedUserId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example: {"msg": "No such user", "result": "error"}
description: |
An example JSON response for when the user is nonexistent or inaccessible:
- allOf:
- $ref: "#/components/schemas/JsonError"
- example: {"msg": "User is not muted", "result": "error"}
description: |
An example JSON response for when the user is not previously muted:
/users/{user_id}/subscriptions/{stream_id}:
get:
operationId: get-subscription-status
summary: Get subscription status
tags: ["streams"]
description: |
Check whether a user is subscribed to a stream.
`GET {{ api_url }}/v1/users/{user_id}/subscriptions/{stream_id}`
**Changes**: New in Zulip 3.0 (feature level 11).
parameters:
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/StreamIdInPath"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
description: MANUALLY
properties:
result: {}
msg: {}
is_subscribed:
type: boolean
description: |
Whether the user is subscribed to the stream.
example:
{"msg": "", "result": "success", "is_subscribed": false}
/realm/emoji/{emoji_name}:
post:
operationId: upload-custom-emoji
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/only-allow-admins-to-add-emoji).
`POST {{ api_url }}/v1/realm/emoji/{emoji_name}`
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":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/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.
`GET {{ api_url }}/v1/realm/emoji`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
emoji:
type: object
description: |
An object that contains `emoji` objects, each identified with their
emoji ID as the key.
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
example:
{
"result": "success",
"msg": "",
"emoji":
{
"1":
{
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
"deactivated": false,
"author_id": 5,
},
},
}
/realm/profile_fields:
get:
operationId: get-custom-profile-fields
summary: Get all custom profile fields
tags: ["server_and_organizations"]
description: |
Get all the [custom profile fields](/help/add-custom-profile-fields)
configured for the user's organization.
`GET {{ api_url }}/v1/realm/profile_fields`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
custom_fields:
type: array
description: |
An array containing all the custom profile fields defined in this
Zulip organization.
items:
$ref: "#/components/schemas/CustomProfileField"
example:
{
"result": "success",
"msg": "",
"custom_fields":
[
{
"id": 1,
"name": "Phone number",
"type": 1,
"hint": "",
"field_data": "",
"order": 1,
},
{
"id": 2,
"name": "Biography",
"type": 2,
"hint": "What are you known for?",
"field_data": "",
"order": 2,
},
{
"id": 3,
"name": "Favorite food",
"type": 1,
"hint": "Or drink, if you'd prefer",
"field_data": "",
"order": 3,
},
{
"id": 4,
"name": "Favorite editor",
"type": 3,
"hint": "",
"field_data": '{"vim":{"text":"Vim","order":"1"},"emacs":{"text":"Emacs","order":"2"}}',
"order": 4,
},
{
"id": 5,
"name": "Birthday",
"type": 4,
"hint": "",
"field_data": "",
"order": 5,
},
{
"id": 6,
"name": "Favorite website",
"type": 5,
"hint": "Or your personal blog's URL",
"field_data": "",
"order": 6,
},
{
"id": 7,
"name": "Mentor",
"type": 6,
"hint": "",
"field_data": "",
"order": 7,
},
{
"id": 8,
"name": "GitHub",
"type": 7,
"hint": "Enter your GitHub username",
"field_data": '{"subtype":"github"}',
"order": 8,
},
],
}
patch:
operationId: reorder-custom-profile-fields
summary: Reorder custom profile fields
tags: ["server_and_organizations"]
description: |
Reorder the custom profile fields in the user's organization.
`PATCH {{ api_url }}/v1/realm/profile_fields`
Custom profile fields are displayed in Zulip UI widgets in order; this
endpoint allows administrative settings UI to change the field ordering.
This endpoint is used to implement the dragging feature described in the
[custom profile fields documentation](/help/add-custom-profile-fields).
x-requires-administrator: true
parameters:
- name: order
in: query
description: |
A list of the IDs of all the custom profile fields defined in this
organization, in the desired new order.
content:
application/json:
schema:
type: array
items:
type: integer
example: [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
post:
operationId: create-custom-profile-field
summary: Create a custom profile field
tags: ["server_and_organizations"]
description: |
[Create a custom profile field](/help/add-custom-profile-fields) in the user's organization.
`POST {{ api_url }}/v1/realm/profile_fields`
x-requires-administrator: true
parameters:
- name: name
in: query
description: |
The name of the custom profile field, which will appear both in
user-facing settings UI for configuring custom profile fields and
in UI displaying a user's profile.
schema:
type: string
example: "Favorite programming language"
- name: hint
in: query
description: |
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
schema:
type: string
example: "Your favorite programming language."
- name: field_type
in: query
description: |
The field type can be any of the supported custom profile field types. See the
[custom profile fields documentation](/help/add-custom-profile-fields)
more details on what each type means.
- **1**: Short text
- **2**: Long text
- **3**: List of options
- **4**: Date picker
- **5**: Link
- **6**: Person picker
- **7**: External account
schema:
type: integer
example: 3
required: true
- name: field_data
in: query
description: |
Field types 3 (List of options) and 7 (External account) support storing
additional configuration for the field type in the `field_data` attribute.
For field type 3 (List of options), this attribute is a JSON dictionary
defining the choices and the order they will be displayed in the
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
content:
application/json:
schema:
type: object
example:
{
"python": {"text": "Python", "order": "1"},
"java": {"text": "Java", "order": "2"},
}
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
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.
`PATCH {{ api_url }}/v1/realm/user_settings_defaults`
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**: New in Zulip 5.0 (feature level 96).
[new-user-defaults]: /help/configure-default-new-user-settings
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- left_side_userlist
- emojiset
parameters:
- name: dense_mode
in: query
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
schema:
type: boolean
example: true
- name: starred_message_counts
in: query
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
schema:
type: boolean
example: true
- name: fluid_layout_width
in: query
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent topics) on wide screens.
schema:
type: boolean
example: true
- name: high_contrast_mode
in: query
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
schema:
type: boolean
example: true
- name: color_scheme
in: query
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: enable_drafts_synchronization
in: query
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.
schema:
type: boolean
example: true
- name: translate_emoticons
in: query
description: |
Whether to [translate emoticons to emoji](/help/enable-emoticon-translations)
in messages the user sends.
schema:
type: boolean
example: true
- name: display_emoji_reaction_users
in: query
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 total reactions are present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
schema:
type: boolean
example: false
- name: default_view
in: query
description: |
The [default view](/help/configure-default-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent topics view
- "all_messages" - All messages view
schema:
type: string
example: all_messages
- name: escape_navigates_to_default_view
in: query
description: |
Whether the escape key navigates to the
[configured default view](/help/configure-default-view).
**Changes**: New in Zulip 5.0 (feature level 107).
schema:
type: boolean
example: true
- name: left_side_userlist
in: query
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
schema:
type: boolean
example: true
- name: emojiset
in: query
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
schema:
type: string
example: "google"
- name: demote_inactive_streams
in: query
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: enable_stream_desktop_notifications
in: query
description: |
Enable visual desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
description: |
Enable email notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
description: |
Enable mobile notifications for stream messages.
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
description: |
Enable audible desktop notifications for stream messages.
schema:
type: boolean
example: true
- name: notification_sound
in: query
description: |
Notification sound name.
schema:
type: string
example: ding
- name: enable_desktop_notifications
in: query
description: |
Enable visual desktop notifications for private messages and @-mentions.
schema:
type: boolean
example: true
- name: enable_sounds
in: query
description: |
Enable audible desktop notifications for private messages and
@-mentions.
schema:
type: boolean
example: true
- name: email_notifications_batching_period_seconds
in: query
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
schema:
type: integer
example: 120
- name: enable_offline_email_notifications
in: query
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
schema:
type: boolean
example: true
- name: enable_digest_emails
in: query
description: |
Enable digest emails when the user is away.
schema:
type: boolean
example: true
- name: message_content_in_email_notifications
in: query
description: |
Include the message's content in email notifications for new messages.
schema:
type: boolean
example: true
- name: pm_content_in_desktop_notifications
in: query
description: |
Include content of private messages in desktop notifications.
schema:
type: boolean
example: true
- name: wildcard_mentions_notify
in: query
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
schema:
type: boolean
example: true
- name: desktop_icon_count_display
in: query
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unreads
- 2 - Private messages and mentions
- 3 - None
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: realm_name_in_notifications
in: query
description: |
Include organization name in subject of message notification emails.
schema:
type: boolean
example: true
- name: presence_enabled
in: query
description: |
Display the presence status to other users when online.
schema:
type: boolean
example: true
- name: enter_sends
in: query
description: |
Whether pressing Enter in the compose box sends a message
(or saves a message edit).
schema:
type: boolean
example: true
- name: twenty_four_hour_time
in: query
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.
schema:
type: boolean
example: true
- name: send_private_typing_notifications
in: query
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
private messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_stream_typing_notifications
in: query
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
stream messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_read_receipts
in: query
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported:
$ref: "#/components/schemas/IgnoredParametersUnsupported"
example:
{
"ignored_parameters_unsupported":
["desktop_notifications", "demote_streams"],
"msg": "",
"result": "success",
}
/users/me/subscriptions/properties:
post:
operationId: update-subscription-settings
summary: Update subscription settings
tags: ["streams"]
description: |
This endpoint is used to update the user's personal settings for the
streams they are subscribed to, including muting, color, pinning, and
per-stream notification settings.
`POST {{ api_url }}/v1/users/me/subscriptions/properties`
**Changes**: Prior to Zulip 5.0 (feature level 111), response
object included the `subscription_data` in the the
request. The endpoint now returns the more ergonomic
`ignored_parameters_unsupported` field instead.
parameters:
- name: subscription_data
in: query
description: |
A list of objects that describe the changes that should be applied in
each subscription. Each object represents a subscription, and must have
a `stream_id` key that identifies the stream, as well as the `property`
being modified and its new `value`.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
property:
type: string
enum:
- color
- is_muted
- in_home_view
- pin_to_top
- desktop_notifications
- audible_notifications
- push_notifications
- email_notifications
- wildcard_mentions_notify
description: |
One of the stream properties described below:
- `"color"`: The hex value of the user's display color for the stream.
- `"is_muted"`: Whether the stream is [muted](/help/mute-a-stream).<br>
**Changes**: Prior to Zulip 2.1, this feature was represented
by the more confusingly named `in_home_view` (with the
opposite value: `in_home_view=!is_muted`); for
backwards-compatibility, modern Zulip still accepts that property.
- `"pin_to_top"`: Whether to pin the stream at the top of the stream list.
- `"desktop_notifications"`: Whether to show desktop notifications
for all messages sent to the stream.
- `"audible_notifications"`: Whether to play a sound
notification for all messages sent to the stream.
- `"push_notifications"`: Whether to trigger a mobile push
notification for all messages sent to the stream.
- `"email_notifications"`: Whether to trigger an email
notification for all messages sent to the stream.
- `"wildcard_mentions_notify"`: Whether wildcard mentions trigger
notifications as though they were personal mentions in this stream.
value:
oneOf:
- type: boolean
- type: string
description: |
The new value of the property being modified.
If the property is `"color"`, then `value` is a string
representing the hex value of the user's display
color for the stream. For all other above properties,
`value` is a boolean.
required:
- stream_id
- property
- value
example:
{"stream_id": 2, "property": "is_muted", "value": true}
example:
[
{"stream_id": 1, "property": "pin_to_top", "value": true},
{"stream_id": 3, "property": "color", "value": "#f00f00"},
]
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported:
$ref: "#/components/schemas/IgnoredParametersUnsupported"
example:
{
"ignored_parameters_unsupported": ["invalid_parameter"],
"result": "success",
"msg": "",
}
/users/{email}:
get:
operationId: get-user-by-email
summary: Get a user by email
tags: ["users"]
description: |
Fetch details for a single user in the organization given a Zulip display
email address.
`GET {{ api_url }}/v1/users/{email}`
Note that this endpoint uses Zulip display emails addresses
for organizations that have configured limited [email address
visibility](/help/restrict-visibility-of-email-addresses).
You can also fetch details on [all users in the organization](/api/get-users) or
[by user ID](/api/get-user). Fetching by user ID is generally recommended
when possible, as users can
[change their email address](/help/change-your-email-address).
_This endpoint is new in Zulip Server 4.0 (feature level 39)._
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
parameters:
- name: email
in: path
description: |
The email address of the user whose details you want to fetch.
schema:
type: string
example: iago@zulip.com
required: true
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
user:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"user":
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "vim"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
},
}
/users/{user_id}:
get:
operationId: get-user
summary: Get a user
tags: ["users"]
description: |
Fetch details for a single user in the organization.
`GET {{ api_url }}/v1/users/{user_id}`
You can also fetch details on [all users in the organization](/api/get-users)
or [by email](/api/get-user-by-email).
_This endpoint is new in Zulip Server 3.0 (feature level 1)._
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: exclude
parameters:
enum:
- ""
description: |
You may pass the `client_gravatar` or `include_custom_profile_fields` query parameter as follows:
parameters:
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/ClientGravatar"
- $ref: "#/components/parameters/IncludeCustomProfileFields"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
user:
$ref: "#/components/schemas/User"
example:
{
"msg": "",
"result": "success",
"user":
{
"date_joined": "2019-10-20T07:50:53.729659+00:00",
"full_name": "King Hamlet",
"is_guest": false,
"profile_data":
{
"4": {"value": "vim"},
"2":
{
"value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius",
"rendered_value": "<p>I am:</p>\n<ul>\n<li>The prince of Denmark</li>\n<li>Nephew to the usurping Claudius</li>\n</ul>",
},
"5": {"value": "1900-01-01"},
"7": {"value": "[11]"},
"6": {"value": "https://blog.zulig.org"},
"1":
{
"value": "+0-11-23-456-7890",
"rendered_value": "<p>+0-11-23-456-7890</p>",
},
"8": {"value": "zulipbot"},
"3":
{
"rendered_value": "<p>Dark chocolate</p>",
"value": "Dark chocolate",
},
},
"user_id": 10,
"is_bot": false,
"bot_type": null,
"timezone": "",
"is_admin": false,
"is_owner": false,
"is_billing_admin": false,
"role": 400,
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
"is_active": true,
"email": "hamlet@zulip.com",
},
}
patch:
operationId: update-user
summary: Update a user
tags: ["users"]
x-requires-administrator: true
description: |
Administrative endpoint to update the details of another user in the organization.
`PATCH {{ api_url }}/v1/users/{user_id}`
Supports everything an administrator can do to edit details of another
user's account, including editing full name,
[role](/help/roles-and-permissions), and [custom profile
fields](/help/add-custom-profile-fields).
parameters:
- $ref: "#/components/parameters/UserId"
- name: full_name
in: query
description: |
The user's full name.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 5.0 (feature level 106).
schema:
type: string
example: NewName
required: false
- name: role
in: query
description: |
New [role](/api/roles-and-permissions) for the user. Roles are encoded as:
- Organization owner: 100
- Organization administrator: 200
- Organization moderator: 300
- Member: 400
- Guest: 600
Only organization owners can add or remove the owner role.
The owner role cannot be removed from the only organization owner.
**Changes**: New in Zulip 3.0 (feature level 8), replacing the previous
pair of `is_admin` and `is_guest` boolean parameters. Organization moderator
role added in Zulip 4.0 (feature level 60).
schema:
type: integer
example: 400
required: false
- name: profile_data
in: query
description: |
A dictionary containing the to be updated custom profile field data for the user.
content:
application/json:
schema:
type: array
items:
type: object
example:
[{"id": 4, "value": "vim"}, {"id": 5, "value": "1909-04-05"}]
required: false
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"result": "error",
"msg": "Guests cannot be organization administrators",
"code": "BAD_REQUEST",
}
description: |
A typical unsuccessful JSON response:
delete:
operationId: deactivate-user
summary: Deactivate a user
tags: ["users"]
x-requires-administrator: true
description: |
[Deactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
`DELETE {{ api_url }}/v1/users/{user_id}`
parameters:
- $ref: "#/components/parameters/UserId"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"msg": "Cannot deactivate the only organization owner",
"result": "error",
}
description: |
An example JSON error response when attempting to deactivate the only
organization owner in an organization:
/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.
`GET {{ api_url }}/v1/realm/linkifiers`
**Changes**: New in Zulip 4.0 (feature level 54). On older versions,
a similar `GET /realm/filters` endpoint was available with each entry in
a `[pattern, url_format, id]` tuple format.
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
linkifiers:
type: array
description: |
An array of objects, where each object describes a linkifier.
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The string regex pattern which represents the pattern that
should be linkified by this linkifier.
url_format:
type: string
description: |
The URL format string to be used for linkifying matches.
id:
type: integer
description: |
The ID of the linkifier.
example:
{
"msg": "",
"linkifiers":
[
{
"pattern": "#(?P<id>[0-9]+)",
"url_format": "https://github.com/zulip/zulip/issues/%(id)s",
"id": 1,
},
],
"result": "success",
}
/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.
`POST {{ api_url }}/v1/realm/filters`
parameters:
- $ref: "#/components/parameters/LinkifierPattern"
- $ref: "#/components/parameters/LinkifierURLFormatString"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
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.
`DELETE {{ api_url }}/v1/realm/filters/{filter_id}`
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":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
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.
`PATCH {{ api_url }}/v1/realm/filters/{filter_id}`
**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: 2
required: true
- $ref: "#/components/parameters/LinkifierPattern"
- $ref: "#/components/parameters/LinkifierURLFormatString"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/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.
`POST {{ api_url }}/v1/realm/playgrounds`
**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was
fixed in Zulip 4.0 (feature level 57).
parameters:
- name: name
in: query
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.
schema:
type: string
example: Python playground
required: true
- name: pygments_language
in: query
description: |
The name of the Pygments language lexer for that
programming language.
schema:
type: string
example: Python
required: true
- name: url_prefix
in: query
description: |
The url prefix for the playground.
schema:
type: string
example: https://python.example.com
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
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.
`DELETE {{ api_url }}/v1/realm/playgrounds/{playground_id}`
**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":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
/register:
post:
operationId: register-queue
summary: Register an event queue
tags: ["real_time_events"]
description: |
`POST {{ api_url }}/v1/register`
This powerful endpoint can be used to register a Zulip "event queue"
(subscribed to certain types of "events", or updates to the messages
and other Zulip data the current user has access to), as well as to
fetch the current state of that data.
(`register` also powers the `call_on_each_event` Python API, and is
intended primarily for complex applications for which the more convenient
`call_on_each_event` API is insufficient).
This endpoint returns a `queue_id` and a `last_event_id`; these can be
used in subsequent calls to the
["events" endpoint](/api/get-events) to request events from
the Zulip server using long-polling.
The server will queue events for up to 10 minutes of inactivity.
After 10 minutes, your event queue will be garbage-collected. The
server will send `heartbeat` events every minute, which makes it easy
to implement a robust client that does not miss events unless the
client loses network connectivity with the Zulip server for 10 minutes
or longer.
Once the server garbage-collects your event queue, the server will
[return an error](/api/get-events#bad_event_queue_id-errors)
with a code of `BAD_EVENT_QUEUE_ID` if you try to fetch events from
the event queue. Your software will need to handle that error
condition by re-initializing itself (e.g. this is what triggers your
browser reloading the Zulip web app when your laptop comes back online
after being offline for more than 10 minutes).
When prototyping with this API, we recommend first calling `register`
with no `event_types` parameter to see all the available data from all
supported event types. Before using your client in production, you
should set appropriate `event_types` and `fetch_event_types` filters
so that your client only requests the data it needs. A few minutes
doing this often saves 90% of the total bandwidth and other resources
consumed by a client using this API.
See the
[events system developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/events-system.html)
if you need deeper details about how the Zulip event queue system
works, avoids clients needing to worry about large classes of
potentially messy races, etc.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- event_types
parameters:
- name: apply_markdown
in: query
description: |
Set to `true` if you would like the content to be rendered in HTML
format (otherwise the API will return the raw text that the user
entered)
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/ClientGravatar"
- name: slim_presence
in: query
description: |
Setting this to `true` will make presence dictionaries be keyed by
user_id instead of email.
**Changes**: New in Zulip 3.0 (Unstable with no feature level yet).
schema:
type: boolean
default: false
example: true
- $ref: "#/components/parameters/Event_types"
- $ref: "#/components/parameters/AllPublicStreams"
- $ref: "#/components/parameters/IncludeSubscribers"
- name: client_capabilities
in: query
description: |
Dictionary containing details on features the client supports that are
relevant to the format of responses sent by the server.
- `notification_settings_null`: Boolean for whether the
client can handle the current API with null values for
stream-level notification settings (which means the stream
is not customized and should inherit the user's global
notification settings for stream messages).
<br />
New in Zulip 2.1.0; in earlier Zulip releases, stream-level
notification settings were simple booleans.
- `bulk_message_deletion`: Boolean for whether the client's
handler for the `delete_message` event type has been
updated to process the new bulk format (with a
`message_ids`, rather than a singleton `message_id`).
Otherwise, the server will send `delete_message` events
in a loop.
<br />
New in Zulip 3.0 (feature level 13). This
capability is for backwards-compatibility; it will be
required in a future server release.
- `user_avatar_url_field_optional`: Boolean for whether the
client required avatar URLs for all users, or supports
using `GET /avatar/{user_id}` to access user avatars. If the
client has this capability, the server may skip sending a
`avatar_url` field in the `realm_user` at its sole discretion
to optimize network performance. This is an important optimization
in organizations with 10,000s of users.
<br />
New in Zulip 3.0 (feature level 18).
- `stream_typing_notifications`: Boolean for whether the client
supports stream typing notifications.
<br />
New in Zulip 4.0 (feature level 58). This capability is
for backwards-compatibility; it will be required in a
future server release.
- `user_settings_object`: Boolean for whether the client supports the modern
`user_settings` event type. If False, the server will additionally send the
legacy `update_display_settings` and `update_global_notifications` event
types for backwards-compatibility with clients that predate this API migration.
<br />
<br />
Because the feature level 89 API changes were merged together, clients can
safely make a request with this client capability and requesting all of the
`user_settings`, `update_display_settings`, and
`update_global_notifications` event types, and get exactly one copy of
settings data on any server version. (And then use the `zulip_feature_level`
in the `/register` response or the presence/absence of a `user_settings` key
to determine where to look).
<br />
New in Zulip 5.0 (feature level 89). This capability is for
backwards-compatibility; it will be removed in a future server release.
content:
application/json:
schema:
type: object
example: {"notification_settings_null": true}
- name: fetch_event_types
in: query
description: |
Same as the `event_types` parameter except that the values in
`fetch_event_types` are used to fetch initial data. If
`fetch_event_types` is not provided, `event_types` is used and if
`event_types` is not provided, this parameter defaults to `None`.
Event types not supported by the server are ignored, in order to simplify
the implementation of client apps that support multiple server versions.
content:
application/json:
schema:
type: array
items:
type: string
example: ["message"]
- $ref: "#/components/parameters/Narrow"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
queue_id:
type: string
nullable: true
description: |
The ID of the queue that has been allocated for your client.
Will be None only for unauthenticated access in realms that have
enabled the [public access option](/help/public-access-option).
last_event_id:
type: integer
description: |
The initial value of `last_event_id` to pass to `GET /api/v1/events`.
zulip_feature_level:
type: integer
description: |
The server's current [Zulip feature level](/api/changelog).
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_verson` 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 the server does not know its `merge-base`.
**Changes**: New in Zulip 5.0 (feature level 88).
alert_words:
type: array
description: |
Present if `alert_words` is present in `fetch_event_types`.
An array of strings, each an [alert word](/help/pm-mention-alert-notifications#alert-words)
that the current user has configured.
items:
type: string
custom_profile_fields:
type: array
description: |
Present if `custom_profile_fields` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains the
details of a single custom profile field that is available to users
in this Zulip organization. This must be combined with the custom profile
field values on individual user objects to display users' full profiles.
items:
$ref: "#/components/schemas/CustomProfileField"
custom_profile_field_types:
type: object
description: |
Present if `custom_profile_fields` is present in `fetch_event_types`.
An array of objects; each object describes a type of custom profile field
that could be configured on this Zulip server. Each custom profile type
has a id and the `type` property of a custom profile field is equal
to one of these ids.
This attribute is only useful for clients containing UI for changing
the set of configured custom profile fields in a Zulip organization.
additionalProperties:
type: object
description: |
`{FIELD_TYPE}`: Dictionary which contains the details
of the field type with the field type as the name of the
property itself. The current supported field types are as follows:
- `SHORT_TEXT`
- `LONG_TEXT`
- `DATE` for date-based fields.
- `CHOICE` for a list of options.
- `URL` for links.
- `EXTERNAL_ACCOUNT` for external accounts.
- `USER` for selecting a user for the field.
additionalProperties: false
properties:
id:
type: integer
description: |
The id of the custom profile field type.
name:
type: string
description: |
The name of the custom profile field type.
demo_organization_scheduled_deletion_date:
type: integer
description: |
Present if the realm is a demo organization.
The UNIX timestamp (UTC) when the demo organization will be
automatically deleted. Clients should use this to display a
prominent warning to the user that the organization will be
deleted at the indicated time.
**Changes**: New in Zulip 5.0 (feature level 94).
drafts:
type: array
description: |
An array containing draft objects for the user. These drafts are being
stored on the backend for the purpose of syncing across devices. This
array will be empty if `enable_drafts_synchronization` is set to `false`.
items:
$ref: "#/components/schemas/Draft"
hotspots:
type: array
description: |
Present if `hotspots` is present in `fetch_event_types`.
An array of dictionaries, where each dictionary contains details about
a single onboarding hotspot that should be shown to new users.
We expect that only official Zulip clients will interact with these data.
items:
$ref: "#/components/schemas/Hotspot"
max_message_id:
type: integer
deprecated: true
description: |
Present if `message` is present in `fetch_event_types`.
The highest message ID among all messages the user has received as of the
moment of this request.
**Deprecated**: This field may be removed in future versions as it no
longer has a clear purpose. Clients wishing to fetch the latest messages
should pass `anchor="latest"` to `GET /messages`.
max_stream_name_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a stream name. Clients should use
these properties rather than hardcoding field sizes, as they may
change in a future Zulip release.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this required `stream` in `fetch_event_types`, was called
`stream_name_max_length`, and always had value 60.
max_stream_description_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a stream description. Clients should use
these properties rather than hardcoding field sizes, as they may
change in a future Zulip release.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this required `stream` in `fetch_event_types`, was called
`stream_description_max_length`, and always had value 1024.
max_topic_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a topic. Clients should use
these properties rather than hardcoding field sizes, as they may
change in a future Zulip release.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this always had value 60.
max_message_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum allowed length for a message. Clients should use
these properties rather than hardcoding field sizes, as they may
change in a future Zulip release.
**Changes**: New in Zulip 4.0 (feature level 53). Previously,
this always had value 10000.
muted_topics:
type: array
description: |
Present if `muted_topics` is present in `fetch_event_types`.
Array of tuples, where each tuple describes a muted topic.
The first element of tuple is the stream name in which the topic
has to be muted, the second element is the topic name to be muted
and the third element is an integer UNIX timestamp representing
when the topic was muted.
items:
type: array
items:
oneOf:
- type: string
- type: integer
muted_users:
type: array
description: |
Present if `muted_users` is present in `fetch_event_types`.
A list of dictionaries where each dictionary describes
a [muted user](/api/mute-user).
**Changes**: New in Zulip 4.0 (feature level 48).
items:
type: object
additionalProperties: false
description: |
Object containing the user id and timestamp of a muted user.
properties:
id:
type: integer
description: |
The ID of the muted user.
timestamp:
type: integer
description: |
An integer UNIX timestamp representing when the user was muted.
presences:
type: object
description: |
Present if `presence` is present in `fetch_event_types`.
A dictionary where each entry describes the presence details for another
user in the Zulip organization.
Users who have been offline for multiple weeks may not appear in this object.
additionalProperties:
type: object
description: |
`{user_id} or {user_email}`: Depending on the value of `slim_presence`.
Each entry contains the details of the presence of the user with the specific
id or email.
additionalProperties:
$ref: "#/components/schemas/Presence"
server_timestamp:
type: number
description: |
Present if `presence` is present in `fetch_event_types`.
The time when the server fetched the
`presences` data included in the response.
Matches the similar field in presence
responses.
**Changes**: New in Zulip 5.0 (feature level 70).
realm_domains:
type: array
description: |
Present if `realm_domains` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a domain within
which users can join the organization without and invitation.
items:
$ref: "#/components/schemas/RealmDomain"
realm_emoji:
description: |
Present if `realm_emoji` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a custom
emoji that has been uploaded in this Zulip organization.
oneOf:
- type: object
additionalProperties:
$ref: "#/components/schemas/RealmEmoji"
- type: array
items:
type: integer
realm_linkifiers:
type: array
description: |
Present if `realm_linkifiers` is present in `fetch_event_types`.
Array of objects where each object describes a single
[linkifier](/help/add-a-custom-linkifier).
**Changes**: New in Zulip 4.0 (feature level 54). Clients can
access these data on older server versions via the previous
`realm_filters` key.
items:
type: object
additionalProperties: false
properties:
pattern:
type: string
description: |
The string regex pattern which represents the pattern that
should be linkified on matching.
url_format:
type: string
description: |
The URL with which the pattern matching string should be linkified.
id:
type: integer
description: |
The ID of the linkifier.
realm_filters:
type: array
deprecated: true
items:
type: array
items:
oneOf:
- type: integer
- type: string
description: |
Legacy property for linkifiers. Present if `realm_filters` is
present in `fetch_event_types`.
An array of tuples (fixed-length arrays) where each tuple describes
a single [linkifier](/help/add-a-custom-linkifier).
The first element of the tuple is a string regex pattern which represents
the pattern that should be linkified on matching.
The second element is the URL with which the
pattern matching string should be linkified with and the third element
is the id of the realm filter.
**Changes**: Deprecated in Zulip 4.0 (feature level 54), replaced by
the `realm_linkifiers` key instead.
realm_playgrounds:
type: array
items:
$ref: "#/components/schemas/RealmPlayground"
description: |
Present if `realm_playgrounds` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a
[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.
**Changes**: New in Zulip 4.0 (feature level 49).
realm_user_groups:
type: array
items:
$ref: "#/components/schemas/UserGroup"
description: |
Present if `realm_user_groups` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a
[user group](/help/user-groups) in the Zulip organization.
realm_bots:
type: array
items:
$ref: "#/components/schemas/Bot"
description: |
Present if `realm_bot` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes a bot that the
current user can administer. If the current user is an organization
administrator, this will include all bots in the organization. Otherwise,
it will only include bots owned by the user (either because the user created
the bot or an administrator transferred the bot's ownership to the user).
realm_embedded_bots:
type: array
items:
type: object
additionalProperties: false
description: |
Object containing details of an embedded bot. Embedded bots are an experimental
feature not enabled in production yet.
properties:
name:
type: string
description: |
The name of the bot.
config:
$ref: "#/components/schemas/Config"
description: |
Present if `realm_embedded_bots` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes an type of embedded
bot that is available to be configured on this Zulip server.
Clients only need these data if they contain UI for creating or administering bots.
realm_incoming_webhook_bots:
description: |
Present if `realm_incoming_webhook_bots` is present in `fetch_event_types`.
An array of dictionaries where each dictionary describes an type of incoming webhook
integration that is available to be configured on this Zulip server.
Clients only need these data if they contain UI for creating or administering bots.
type: array
items:
type: object
additionalProperties: false
description: |
Object containing details of the bot.
properties:
name:
type: string
description: |
The name of the bot.
config:
$ref: "#/components/schemas/Config"
recent_private_conversations:
description: |
Present if `recent_private_conversations` is present in `fetch_event_types`.
An array of dictionaries containing data on all private message and group private message
conversations that the user has received (or sent) messages in, organized by
conversation. This data set is designed to support UI elements such as the
"Private messages" widget in the web application showing recent private message
conversations that the user has participated in.
"Recent" is defined as the server's discretion; the original implementation
interpreted that as "the 1000 most recent private messages the user received".
type: array
items:
type: object
additionalProperties: false
description: |
Object describing a single recent private conversation in the user's history.
properties:
max_message_id:
type: integer
description: |
The highest message id of the conversation, intended to support sorting
the conversations by recency.
user_ids:
type: array
items:
type: integer
description: |
The list of users other than the current user in the private message
conversation. This will be an empty list for private messages sent to
oneself.
subscriptions:
type: array
items:
$ref: "#/components/schemas/Subscriptions"
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes the properties
of a stream the user is subscribed to (as well as that user's
personal per-stream settings).
unsubscribed:
type: array
items:
$ref: "#/components/schemas/Subscriptions"
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes one of the
streams the user has unsubscribed from but was previously subscribed to
along with the subscription details.
Unlike `never_subscribed`, the user might have messages in their personal
message history that were sent to these streams.
never_subscribed:
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer.
Null means the stream was recently created and there is
insufficient data to estimate the average traffic.
subscribers:
type: array
items:
type: integer
description: |
A list of user IDs of users who are subscribed
to the stream. Included only if `include_subscribers` is `true`.
If a user is not allowed to know the subscribers for
a stream, we will send an empty array. API authors
should use other data to determine whether users like
guest users are forbidden to know the subscribers.
description: |
Present if `subscription` is present in `fetch_event_types`.
A array of dictionaries where each dictionary describes one of the
streams that is visible to the user and the user has never been subscribed
to.
Important for clients containing UI where one can browse streams to subscribe
to.
unread_msgs:
type: object
items:
$ref: "#/components/schemas/BasicStream"
description: |
Present if `message` and `update_message_flags` are both present in
`event_types`.
A set of data structures describing the conversations containing
the 50000 most recent unread messages the user has received. This will usually
contain every unread message the user has received, but clients should support
users with even more unread messages (and not hardcode the number 50000).
additionalProperties: false
properties:
count:
type: integer
description: |
The total number of unread messages to display; this includes private
and group private messages, as well as all messages to unmuted topics
on unmuted streams.
pms:
type: array
description: |
An array of dictionaries where each entry contains details
of unread private messages with a specific user.
items:
type: object
description: |
Object containing the details of a unread private message with
a specific user. Note that in rare situations, it is possible
for a message that you sent to another user to be marked as
unread and thus appear here.
additionalProperties: false
properties:
other_user_id:
type: integer
description: |
The user id of the other participant in this non-group private
message conversation. Will be your own user ID for messages
that you sent to only yourself.
sender_id:
deprecated: true
type: integer
description: |
Old name for `other_user_id`. Clients should access this
field in Zulip server versions that do not yet support
`other_user_id`.
**Changes**: Deprecated in Zulip 5.0 (feature level 119).
We expect to provide a next version of the full `unread_msgs`
API before removing this legacy name.
message_ids:
type: array
description: |
The message ids of the recent unread PM messages sent by the other user.
items:
type: integer
streams:
type: array
description: |
An array of dictionaries where each dictionary contains
details of all unread messages of a single subscribed stream,
including muted streams.
**Changes**: Prior to Zulip 5.0 (feature level 90), the
dictionaries included an additional `sender_ids` key listing
the set of IDs of users who had sent the unread messages.
items:
type: object
description: |
`{message_id}`: Object containing the details of a unread stream
message with the message_id as the key.
additionalProperties: false
properties:
topic:
type: string
description: |
The topic under which the message was sent.
stream_id:
type: integer
description: |
The id of the stream to which the message was sent.
unread_message_ids:
type: array
description: |
The message ids of the recent unread messages sent in this stream.
items:
type: integer
huddles:
type: array
description: |
An array of dictionaries where each dictionary contains
details of all unread group private messages of a single
group.
items:
type: object
description: |
Object containing the details of a unread group PM
messages of a single group.
additionalProperties: false
properties:
user_ids_string:
type: string
description: |
A string containing the IDs of all users in the group
private message conversation separated by commas
(,). Example: "1,2,3".
message_ids:
type: array
description: |
The message ids of the recent unread messages which have been sent in
this group.
items:
type: integer
mentions:
type: array
description: |
Array containing the ids of all messages in which the user has been mentioned.
For muted streams, wildcard mentions will not be considered for this array.
items:
type: integer
old_unreads_missing:
type: boolean
description: |
True if this data set was truncated because the user has too many
unread messages. When truncation occurs, only the most recent
`MAX_UNREAD_MESSAGES` (currently 50000) messages will be considered
when forming this response. When true, we recommend that clients
display a warning, as they are likely to produce erroneous results
until reloaded with the user having fewer than `MAX_UNREAD_MESSAGES`
unread messages.
**Changes**: New in Zulip 4.0 (feature level 44).
starred_messages:
type: array
items:
type: integer
description: |
Present if `starred_messages` is present in `fetch_event_types`.
Array containing the ids of all messages which have been
[starred](/help/star-a-message) by the user.
streams:
type: array
items:
$ref: "#/components/schemas/BasicStream"
description: |
Present if `stream` is present in `fetch_event_types`.
Array of dictionaries where each dictionary contains details about
a single stream in the organization that is visible to the user.
For organization administrators, this will include all private streams
in the organization.
realm_default_streams:
type: array
items:
$ref: "#/components/schemas/BasicStream"
description: |
Present if `default_streams` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains details
about a single [default stream](/help/set-default-streams-for-new-users)
for the Zulip organization.
realm_default_stream_groups:
type: array
items:
$ref: "#/components/schemas/DefaultStreamGroup"
description: |
Present if `default_stream_groups` is present in `fetch_event_types`.
An array of dictionaries where each dictionary contains details
about a single default stream group configured for this
Zulip organization.
Default stream groups are an experimental feature.
stop_words:
type: array
items:
type: string
description: |
Present if `stop_words` is present in `fetch_event_types`.
An array containing the stop words used by the Zulip server's
full-text search implementation. Useful for showing helpful
error messages when a search returns limited results because
a stop word in the query was ignored.
user_status:
type: object
description: |
Present if `user_status` is present in `fetch_event_types`.
A dictionary which contains the [status](/help/status-and-availability)
of all users in the Zulip organization who have set a status.
**Changes**: The emoji parameters are new in Zulip 5.0 (feature level 86).
Previously, Zulip did not support emoji associated with statuses.
additionalProperties:
description: |
`{user_id}`: Object containing the status details of a user
with the key of the object being the id of the user.
type: object
additionalProperties: false
properties:
away:
type: boolean
description: |
If present, the user has marked themself "away".
status_text:
type: string
description: |
If present, the text content of the user's status message.
emoji_name:
type: string
description: |
If present, the name for the emoji to associate with the user's status.
**Changes**: New in Zulip 5.0 (feature level 86).
emoji_code:
type: string
description: |
If present, a unique identifier, defining the specific emoji codepoint
requested, within the namespace of the `reaction_type`.
**Changes**: New in Zulip 5.0 (feature level 86).
reaction_type:
type: string
description: |
If present, a string indicating the type of emoji. Each emoji
`reaction_type` has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: New in Zulip 5.0 (feature level 86).
user_settings:
type: object
description: |
Present if `user_settings` is present in `fetch_event_types`.
A dictionary containing the user's personal settings.
**Changes**: New in Zulip 5.0 (feature level 89). Previously,
these settings appeared in the top-level object, where they are
available for clients without the `user_settings_object` client
capability for backwards-compatibility.
additionalProperties: false
properties:
twenty_four_hour_time:
type: boolean
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
dense_mode:
type: boolean
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
starred_message_counts:
type: boolean
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
fluid_layout_width:
type: boolean
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent topics) on wide screens.
high_contrast_mode:
type: boolean
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
color_scheme:
type: integer
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.
translate_emoticons:
type: boolean
description: |
Whether to [translate emoticons to emoji](/help/enable-emoticon-translations)
in messages the user sends.
display_emoji_reaction_users:
type: boolean
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 total reactions are
present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
default_language:
type: string
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
default_view:
type: string
description: |
The [default view](/help/configure-default-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent topics view
- "all_messages" - All messages view
escape_navigates_to_default_view:
type: boolean
description: |
Whether the escape key navigates to the
[configured default view](/help/configure-default-view).
**Changes**: New in Zulip 5.0 (feature level 107).
left_side_userlist:
type: boolean
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
emojiset:
type: string
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
demote_inactive_streams:
type: integer
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
timezone:
type: string
description: |
The user's [configured time zone](/help/change-your-timezone).
Time zone values supported by the server are served at
[/static/generated/timezones.json](/static/generated/timezones.json).
enter_sends:
type: boolean
description: |
Whether the user setting for [sending on pressing Enter](/help/enable-enter-to-send)
in the compose box is enabled.
enable_drafts_synchronization:
type: boolean
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.
enable_stream_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for stream messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for stream messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for stream messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for stream messages.
notification_sound:
type: string
description: |
Notification sound name.
enable_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for private messages and @-mentions.
enable_sounds:
type: boolean
description: |
Enable audible desktop notifications for private messages and
@-mentions.
email_notifications_batching_period_seconds:
type: integer
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
enable_offline_email_notifications:
type: boolean
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
enable_offline_push_notifications:
type: boolean
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
enable_online_push_notifications:
type: boolean
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
enable_digest_emails:
type: boolean
description: |
Enable digest emails when the user is away.
enable_marketing_emails:
type: boolean
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
enable_login_emails:
type: boolean
description: |
Enable email notifications for new logins to account.
message_content_in_email_notifications:
type: boolean
description: |
Include the message's content in email notifications for new messages.
pm_content_in_desktop_notifications:
type: boolean
description: |
Include content of private messages in desktop notifications.
wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
desktop_icon_count_display:
type: integer
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unreads
- 2 - Private messages and mentions
- 3 - None
realm_name_in_notifications:
type: boolean
description: |
Include organization name in subject of message notification emails.
presence_enabled:
type: boolean
description: |
Display the presence status to other users when online.
available_notification_sounds:
type: array
items:
type: string
description: |
Array containing the names of the notification sound options
supported by this Zulip server. Only relevant to support UI
for configuring notification sounds.
emojiset_choices:
description: |
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
send_private_typing_notifications:
type: boolean
description: |
Whether the user has chosen to send [typing
notifications](/help/status-and-availability#typing-notifications)
when composing private messages. The client should send typing
notifications for private messages if and only if this setting is enabled.
**Changes**: New in Zulip 5.0 (feature level 105).
send_stream_typing_notifications:
type: boolean
description: |
Whether the user has chosen to send [typing
notifications](/help/status-and-availability#typing-notifications)
when composing stream messages. The client should send typing
notifications for stream messages if and only if this setting is enabled.
**Changes**: New in Zulip 5.0 (feature level 105).
send_read_receipts:
type: boolean
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
has_zoom_token:
type: boolean
description: |
Present if `video_calls` is present in `fetch_event_types`.
A boolean which signifies whether the user has a zoom token and has thus completed
OAuth flow for the [Zoom integration](/help/start-a-call). Clients need
to know whether initiating Zoom OAuth is required before creating a Zoom call.
giphy_api_key:
type: string
description: |
Present if `giphy` is present in `fetch_event_types`.
GIPHY's client-side SDKs needs this API key to use the GIPHY API.
GIPHY API keys are not secret (their main purpose appears to be
allowing GIPHY to block a problematic app). Please don't use our API
key for an app unrelated to Zulip.
Developers of clients should also read the
[GIPHY API TOS](https://support.giphy.com/hc/en-us/articles/360028134111-GIPHY-API-Terms-of-Service-)
before using this API key.
**Changes**: Added in Zulip 4.0 (feature level 47).
enable_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_digest_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_login_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_marketing_emails:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
email_notifications_batching_period_seconds:
deprecated: true
type: integer
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_offline_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_offline_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_online_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_sounds:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_stream_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_stream_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_stream_push_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_stream_audible_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
wildcard_mentions_notify:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
message_content_in_email_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
notification_sound:
deprecated: true
type: string
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
pm_content_in_desktop_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
desktop_icon_count_display:
deprecated: true
type: integer
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
realm_name_in_notifications:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
presence_enabled:
deprecated: true
type: boolean
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
The current value of this global notification setting for the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
available_notification_sounds:
deprecated: true
type: array
items:
type: string
description: |
Present if `update_global_notifications` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in their
client_capabilities` when registering the event queue.
Array containing the names of the notification sound options supported by
this Zulip server. Only relevant to support UI for configuring notification
sounds.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
color_scheme:
deprecated: true
type: integer
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
The color scheme selected by the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
default_language:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
The default language chosen by the user.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
demote_inactive_streams:
deprecated: true
type: integer
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen to demote inactive streams.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
dense_mode:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has switched on dense mode. Dense mode is an experimental
feature that is only available in development environments.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
emojiset:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
The name of the emoji set that the user has chosen.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
enable_drafts_synchronization:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`.
Whether drafts synchronization is enabled for the user. If disabled,
clients will receive an error when trying to use the `drafts` endpoints.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
New in Zulip 5.0 (feature level 87).
fluid_layout_width:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen for the layout width to be fluid.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
default_view:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
The [default view](/help/configure-default-view) in Zulip, represented
as the URL suffix after `#` to be rendered when Zulip loads.
Currently supported values are `all_messages` and `recent_topics`.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
high_contrast_mode:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether has switched on high contrast mode.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
left_side_userlist:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen for the userlist to be displayed
on the left side of the screen (for desktop app and web app) in narrow
windows.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
starred_message_counts:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen the number of starred messages to
be displayed similar to unread counts.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
timezone:
deprecated: true
type: string
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
The time zone configured for the user. This is used primarily to display
the user's time zone to other users.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
translate_emoticons:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen for emoticons to be translated into emoji
in the Zulip compose box.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
twenty_four_hour_time:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user has chosen a twenty four hour time display (true)
or a twelve hour one (false).
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
emojiset_choices:
deprecated: true
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and access the `user_settings` object instead.
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
realm_add_custom_emoji_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can upload new custom emoji
in this organization.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
**Changes**: New in Zulip 5.0 (feature level 85) replacing the
previous `realm_add_emoji_by_admins_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_allow_edit_history:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization is configured to allow users to access
[message edit history](/help/view-a-messages-edit-history).
realm_delete_own_message_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] defining which users can delete
messages that they had sent.
- 1 = members only
- 2 = admins only
- 3 = [full members][calc-full-member] only
- 4 = admins and moderators only
- 5 = everyone
**Changes**: New in Zulip 5.0 (feature level 101), replacing the
previous `allow_message_deleting` boolean;
`true` corresponded to `everyone`, and `false` to `admins only`.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_bot_creation_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy](/api/roles-and-permissions#permission-levels)
for which users can create bot users in this organization.
realm_create_public_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can create public streams
in this organization.
- 1 = members only
- 2 = admins only
- 3 = [full members][calc-full-member] only
- 4 = admins and moderators only
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `realm_create_stream_policy` setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_create_private_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can create private streams
in this organization.
- 1 = members only
- 2 = admins only
- 3 = [full members][calc-full-member] only
- 4 = admins and moderators only
**Changes**: Before Zulip 5.0 (feature level 102), permission to
create streams was controlled by the `realm_create_stream_policy` setting.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_create_web_public_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Has no effect and should not be displayed in settings UI
unless the Zulip server has the `WEB_PUBLIC_STREAMS_ENABLED`
server-level setting enabled and the organization has enabled
the `enable_spectator_access` realm setting.
The [policy][permission-level] for which users can create web
public streams in this organization. Allowed
values are:
- 2 = admins only
- 4 = admins and moderators only
- 6 = nobody
- 7 = owners only
**Changes**: Added in Zulip 5.0 (feature level 103).
[permission-level]: /api/roles-and-permissions#permission-levels
realm_invite_to_stream_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy](/api/roles-and-permissions#permission-levels)
for which users can add other users to streams in this organization.
realm_wildcard_mention_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for who can use wildcard mentions
in large streams.
- 1 => Any user can use wildcard mentions in large streams.
- 2 => Only members can use wildcard mentions in large streams.
- 3 => Only [full members][calc-full-member] can use wildcard mentions in large streams.
- 4 => Only stream and organization administrators can use wildcard mentions in large streams.
- 5 => Only organization administrators can use wildcard mentions in large streams.
- 6 => Nobody can use wildcard mentions in large streams.
- 7 => Only organization administrators and moderators can use wildcard mentions in large streams.
All users will receive a warning/reminder when using
mentions in large streams, even when permitted to do so.
**Changes**: New in Zulip 4.0 (feature level 33). Moderators option added in
Zulip 4.0 (feature level 62).
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_default_language:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The [notifications language for the organization](/help/change-the-default-language-for-your-organization).
realm_description:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The description of the organization, used on login and registration pages.
realm_digest_emails_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has enabled [weekly digest emails](/help/digest-emails).
realm_disallow_disposable_email_addresses:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization disallows disposable email
addresses.
realm_email_address_visibility:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users in this organization can see
the real email addresses of other users.
- 1 = everyone
- 2 = members only
- 3 = administrators only
- 4 = nobody (though note that administrators can change this setting).
- 5 = moderators only
[permission-level]: /api/roles-and-permissions#permission-levels
realm_email_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether users are allowed to change their own email address in this
organization. This is typically disabled for organizations that
synchronize accounts from LDAP or a similar corporate database.
realm_invite_required:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether an invitation is required to join this organization.
realm_invite_to_realm_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
[Policy][permission-level] for [who can invite new
users](/help/restrict-account-creation#change-who-can-send-invitations)
to join the organization:
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
- 6 = Nobody
**Changes**: New in Zulip 4.0 (feature level 50) replacing the
previous `realm_invite_by_admins_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_move_messages_between_streams_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can move messages
from one stream to another.
- 1 = Members only
- 2 = Administrators only
- 3 = [Full members][calc-full-member] only
- 4 = Moderators only
**Changes**: New in Zulip 4.0 (feature level 56)
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_inline_image_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization has been configured to enable
[previews of linked images](/help/allow-image-link-previews).
realm_inline_url_embed_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organization has been configured to enable
[previews of linked websites](/help/allow-image-link-previews).
realm_mandatory_topics:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether [topics are required](/help/require-topics) for messages in this organization.
realm_message_retention_days:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The default [message retention policy](/help/message-retention-policy)
for this organization. It can have one special value:
- `-1` denoting that the messages will be retained forever for this realm, by default.
**Changes**: Prior to Zulip 3.0 (feature level 22), no limit was
encoded as `null` instead of `-1`. Clients can correctly handle all
server versions by treating both `-1` and `null` as indicating
unlimited message retention.
realm_name:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The name of the organization, used in login pages etc.
realm_name_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their name
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
realm_avatar_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Indicates whether users are
[allowed to change](/help/restrict-name-and-email-changes) their avatar
via the Zulip UI in this organization. Typically disabled
in organizations syncing this type of account information from
an external user database like LDAP.
realm_emails_restricted_to_domains:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether [new users joining](/help/restrict-account-creation#configuring-email-domain-restrictions)
this organization are required to have an email
address in one of the `realm_domains` configured for the organization.
realm_send_welcome_emails:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether or not this organization is configured to send the standard Zulip
[welcome emails](/help/disable-welcome-emails) to new users joining the organization.
realm_message_content_allowed_in_email_notifications:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether notification emails in this organization are allowed to
contain Zulip the message content, or simply indicate that a new
message was sent.
realm_enable_spectator_access:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether web-public streams and related anonymous access APIs/features
are enabled in this organization.
Can only be enabled if the `WEB_PUBLIC_STREAMS_ENABLED`
[server setting][server-settings] is enabled on the Zulip
server. See also the `create_web_public_stream_policy` realm
setting.
**Changes**: New in Zulip 5.0 (feature level 109).
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
realm_want_advertise_in_communities_directory:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has given permission to be advertised in the
Zulip [communities directory](/help/communities-directory).
Useful only to clients supporting changing this setting for the
organization.
Giving permission via this setting does not guarantee that an
organization will be listed in the Zulip communities directory.
**Changes**: New in Zulip 6.0 (feature level 129).
realm_video_chat_provider:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The configured video call provider for the organization.
realm_giphy_rating:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The configured GIPHY rating for the organization.
**Changes**: New in Zulip 4.0 (feature level 55).
realm_waiting_period_threshold:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Members whose accounts have been created at least this many days ago
will be treated as [full members][calc-full-member]
for the purpose of settings that restrict access to new members.
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_digest_weekday:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The day of the week when the organization will send
its weekly digest email to inactive users.
realm_private_message_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
[Policy](/api/roles-and-permissions#permission-levels)
for [who can send private messages](/help/restrict-private-messages)
in this organization.
- 1 = Everyone
- 2 = Nobody
realm_user_group_edit_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The organization's [policy][permission-level] for
[who can manage user groups][user-group-permissions].
- 1 = All members can create and edit user groups
- 2 = Only organization administrators can create and edit user groups
- 3 = Only [full members][calc-full-member] can create and edit user groups.
- 4 = Only organization administrators and moderators can create and edit user groups.
[user-group-permissions]: /help/user-groups#configure-who-can-create-and-manage-user-groups
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_default_code_block_language:
type: string
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
The default pygments language code to be used for a code blocks
in this organization. Null if no default has been set.
realm_message_content_delete_limit_seconds:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be deleted
with this organization's
[message deletion policy](/help/configure-message-editing-and-deletion).
Will not be 0. A 'null' value means no limit: messages can be deleted
regardless of how long ago they were sent.
**Changes**: No limit was represented using the
special value `0` before Zulip 5.0 (feature level 100).
realm_authentication_methods:
type: object
additionalProperties:
description: |
Boolean describing whether the authentication method (i.e its key)
is enabled in this organization.
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary of 'authentication_method_name': 'boolean' with each
entry describing whether the authentication name can be used for
authenticating into the organization.
realm_allow_message_editing:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this organizations [message edit policy](/help/configure-message-editing-and-deletion)
allows editing the content of messages.
realm_edit_topic_policy:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [policy][permission-level] for which users can edit topics of any message.
- 1 = members only
- 2 = admins only
- 3 = [full members][calc-full-member] only
- 4 = moderators only
- 5 = everyone
**Changes**: New in Zulip 5.0 (feature level 75), replacing the
previous `allow_community_topic_editing` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
realm_message_content_edit_limit_seconds:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot be edited
with this organization's
[message edit policy](/help/configure-message-editing-and-deletion).
realm_community_topic_editing_limit_seconds:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Messages sent more than this many seconds ago cannot have
their topics edited by other users with this organization's
[message edit policy](/help/configure-message-editing-and-deletion).
**Changes**: New in Zulip 3.0 (feature level 11). Previously this
value was hardcoded to 86400 seconds (1 day).
realm_icon_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's [profile icon](/help/create-your-organization-profile).
realm_icon_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's
[profile icon](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the organization's icon.
- "G" means generated by Gravatar (the default).
- "U" means uploaded by an organization administrator.
max_icon_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size allowed for the organization's
icon. Useful for UI allowing editing the organization's icon.
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `max_icon_file_size`.
realm_logo_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's wide logo configured in the
[organization profile](/help/create-your-organization-profile).
realm_logo_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
realm_night_logo_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL of the organization's dark theme wide-format logo configured in the
[organization profile](/help/create-your-organization-profile).
realm_night_logo_source:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
String indicating whether the organization's dark theme
[profile wide logo](/help/create-your-organization-profile) was uploaded
by a user or is the default. Useful for UI allowing editing the
organization's wide logo.
- "D" means the logo is the default Zulip logo.
- "U" means uploaded by an organization administrator.
max_logo_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size allowed for the uploaded organization logos.
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `max_logo_file_size`.
realm_bot_domain:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The fake email domain that will be used for new bots created this
organization. Useful for UI for creating bots.
realm_uri:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The URL for the organization.
realm_available_video_chat_providers:
type: object
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary where each entry describes a supported
[video call provider](/help/start-a-call)
that is configured on this server and could be selected by an
organization administrator.
Useful for administrative settings UI that allows changing the
video call provider.
additionalProperties:
description: |
`{provider_name}`: Dictionary containing the details of the
video call provider with the name of the chat provider as
the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the video call provider.
id:
type: integer
description: |
The ID of the video call provider.
realm_presence_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether online presence of other users is shown in this
organization.
settings_send_digest_emails:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this Zulip server is configured to allow organizations to
enable [digest emails](/help/digest-emails).
Relevant for administrative settings UI that can change the digest
email settings.
realm_is_zephyr_mirror_realm:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization is a Zephyr mirror realm.
realm_email_auth_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization has enabled Zulip's default email and password
authentication feature. Determines whether Zulip stores a password
for the user and clients should offer any UI for changing the user's
Zulip password.
realm_password_auth_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization allows any sort of password-based
authentication (whether via EmailAuthBackend or LDAP passwords).
Determines whether a client might ever need to display a password prompt
(clients will primarily look at this attribute in [server_settings](/api/get-server-settings)
before presenting a login page).
realm_push_notifications_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether push notifications are enabled for this organization. Typically
`false` for self-hosted servers that have not configured the
[Mobile push notifications service](https://zulip.readthedocs.io/en/latest/production/mobile-push-notifications.html).
realm_upload_quota_mib:
type: integer
nullable: true
description: |
Present if `realm` is present in `fetch_event_types`.
The total quota for uploaded files in this organization.
Clients are not responsible for checking this quota; it is included
in the API only for display purposes.
Null if there is no limit.
**Changes**: New in Zulip 5.0 (feature level 72). Previously,
this was called `realm_upload_quota`.
realm_org_type:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The [organization type](/help/organization-type) for the realm.
Useful only to clients supporting changing this setting for the
organization, or clients implementing onboarding content or
other features that varies with organization type.
- 0 = Unspecified
- 10 = Business
- 20 = Open-source project
- 30 = Education (non-profit)
- 35 = Education (for-profit)
- 40 = Research
- 50 = Event or conference
- 60 = Non-profit (registered)
- 70 = Government
- 80 = Political group
- 90 = Community
- 100 = Personal
- 1000 = Other
**Changes**: New in Zulip 6.0 (feature level 128).
realm_plan_type:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The plan type of the organization.
- 1 = Self-hosted organization (SELF_HOSTED)
- 2 = Zulip Cloud free plan (LIMITED)
- 3 = Zulip Cloud Standard plan (STANDARD)
- 4 = Zulip Cloud Standard plan, sponsored for free (STANDARD_FREE)
zulip_plan_is_not_limited:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the organization is using a limited (Zulip Cloud Free) plan.
upgrade_text_for_wide_organization_logo:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
Text to use when displaying UI for wide organization logos, a feature
that is currently not available on the Zulip Cloud Free plan.
Useful only for clients supporting administrative UI for uploading
a new wide organization logo to brand the organization.
realm_default_external_accounts:
type: object
description: |
Present if `realm` is present in `fetch_event_types`.
Dictionary where each entry describes a default external
account type that can be configured with Zulip's custom
profile fields feature.
additionalProperties:
description: |
`{site_name}`: Dictionary containing the details of the
default external account provider with the name of the
website as the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The name of the external account provider
text:
type: string
description: |
The text describing the external account.
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 for this account.
url_pattern:
type: string
description: |
The regex pattern of the URL of a profile page
on the external site.
jitsi_server_url:
type: string
description: |
Present if `realm` is present in `fetch_event_types`.
The base URL the organization uses to create Jitsi video calls.
development_environment:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether this Zulip server is a development environment. Used
to control certain features or UI (such as error popups)
that should only apply when connected to a Zulip development
environment.
server_generation:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
A timestamp indicating when the process hosting this
event queue was started. Clients will likely only find
this value useful for inclusion in detailed error reports.
password_min_length:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
This Zulip server's configured minimum required length for passwords.
Necessary for password change UI to show whether the password
will be accepted.
password_min_guesses:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
This Zulip server's configured minimum `zxcvbn` minimum guesses.
Necessary for password change UI to show whether the password
will be accepted.
giphy_rating_options:
type: object
description: |
Dictionary where each entry describes a valid rating
that is configured on this server and could be selected by an
organization administrator.
Useful for administrative settings UI that allows changing the
allowed rating of GIFs.
additionalProperties:
description: |
`{rating_name}`: Dictionary containing the details of the
rating with the name of the rating as
the key.
type: object
additionalProperties: false
properties:
name:
type: string
description: |
The description of the rating option.
id:
type: integer
description: |
The ID of the rating option.
max_file_upload_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum file size that can be uploaded to this Zulip server.
max_avatar_file_size_mib:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The maximum avatar size that can be uploaded to this Zulip server.
server_inline_image_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is configured with support for inline image previews.
Clients containing administrative UI for changing
`realm_inline_image_preview` should consult this field before offering
that feature.
server_inline_url_embed_preview:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is configured with support for inline URL previews.
Clients containing administrative UI for changing
`realm_inline_url_embed_preview` should consult this field before offering
that feature.
server_avatar_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server allows avatar changes. Similar to
`realm_avatar_changes_disabled` but based on the `AVATAR_CHANGES_DISABLED`
Zulip server level setting.
server_name_changes_disabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server allows name changes. Similar to
`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`
Zulip server level setting.
server_needs_upgrade:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
Whether the server is running an old version based on the Zulip
[server release lifecycle](https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html#upgrade-nag),
such that the web app will display to the current user a prominent warning.
**Changes**: New in Zulip 5.0 (feature level 74).
server_web_public_streams_enabled:
type: boolean
description: |
Present if `realm` is present in `fetch_event_types`.
The value of the `WEB_PUBLIC_STREAMS_ENABLED` Zulip server level
setting. A server that has disabled this setting intends to not offer [web
public streams](/help/public-access-option) to realms it hosts. (Zulip Cloud
defaults to `True`; self-hosted servers default to `False`).
Clients should use this to determine whether to offer UI for the
realm-level setting for enabling we-public streams
(`realm_enable_spectator_access`).
**Changes**: New in Zulip 5.0 (feature level 110).
event_queue_longpoll_timeout_seconds:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
Recommended client-side HTTP request timeout for [`GET /events`](/api/get-events) calls.
This is guaranteed to be somewhat greater than the heartbeat frequency. It is important
that clients respect this parameter, so that increases in the heartbeat frequency do not
break clients.
**Changes**: New in Zulip 5.0 (feature level 74). Previously,
this was hardcoded to 90 seconds, and clients should use that as a fallback
value when interacting with servers where this field is not present.
realm_notifications_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the stream to which notifications announcing the
creation of new streams are sent. -1 if such notifications are disabled.
Since these notifications are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
realm_signup_notifications_stream_id:
type: integer
description: |
Present if `realm` is present in `fetch_event_types`.
The ID of the stream to which notifications announcing
that new users have joined the organization are sent.
-1 if such notifications are disabled.
Since these notifications are sent by the server, this field is
primarily relevant to clients containing UI for changing it.
realm_user_settings_defaults:
type: object
additionalProperties: false
description: |
Present if `realm_user_settings_defaults` is present in `fetch_event_types`.
A dictionary containing the default values of settings for new users.
**Changes**: New in Zulip 5.0 (feature level 95).
properties:
twenty_four_hour_time:
type: boolean
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
**Changes**: New in Zulip 5.0 (feature level 99).
This value was previously available as
`realm_default_twenty_four_hour_time` in
the top-level response object (only when `realm` was
present in `fetch_event_types`).
dense_mode:
type: boolean
description: |
This setting has no effect at present. It is reserved for use in
controlling the default font size in Zulip.
starred_message_counts:
type: boolean
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
fluid_layout_width:
type: boolean
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent topics) on wide screens.
high_contrast_mode:
type: boolean
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
color_scheme:
type: integer
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.
translate_emoticons:
type: boolean
description: |
Whether to [translate emoticons to emoji](/help/enable-emoticon-translations)
in messages the user sends.
display_emoji_reaction_users:
type: boolean
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 total reactions are
present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
default_language:
type: string
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
default_view:
type: string
description: |
The [default view](/help/configure-default-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent topics view
- "all_messages" - All messages view
escape_navigates_to_default_view:
type: boolean
description: |
Whether the escape key navigates to the
[configured default view](/help/configure-default-view).
**Changes**: New in Zulip 5.0 (feature level 107).
left_side_userlist:
type: boolean
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
emojiset:
type: string
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
demote_inactive_streams:
type: integer
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
enable_stream_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for stream messages.
enable_stream_email_notifications:
type: boolean
description: |
Enable email notifications for stream messages.
enable_stream_push_notifications:
type: boolean
description: |
Enable mobile notifications for stream messages.
enable_stream_audible_notifications:
type: boolean
description: |
Enable audible desktop notifications for stream messages.
notification_sound:
type: string
description: |
Notification sound name.
enable_desktop_notifications:
type: boolean
description: |
Enable visual desktop notifications for private messages and @-mentions.
enable_sounds:
type: boolean
description: |
Enable audible desktop notifications for private messages and
@-mentions.
enable_offline_email_notifications:
type: boolean
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
enable_offline_push_notifications:
type: boolean
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
enable_online_push_notifications:
type: boolean
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
enable_digest_emails:
type: boolean
description: |
Enable digest emails when the user is away.
enable_marketing_emails:
type: boolean
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
enable_login_emails:
type: boolean
description: |
Enable email notifications for new logins to account.
message_content_in_email_notifications:
type: boolean
description: |
Include the message's content in email notifications for new messages.
pm_content_in_desktop_notifications:
type: boolean
description: |
Include content of private messages in desktop notifications.
wildcard_mentions_notify:
type: boolean
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
desktop_icon_count_display:
type: integer
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unreads
- 2 - Private messages and mentions
- 3 - None
realm_name_in_notifications:
type: boolean
description: |
Include organization name in subject of message notification emails.
presence_enabled:
type: boolean
description: |
Display the presence status to other users when online.
enter_sends:
type: boolean
description: |
Whether the user setting for [sending on pressing Enter](/help/enable-enter-to-send)
in the compose box is enabled.
enable_drafts_synchronization:
type: boolean
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.
email_notifications_batching_period_seconds:
type: integer
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
available_notification_sounds:
type: array
items:
type: string
description: |
Array containing the names of the notification sound options
supported by this Zulip server. Only relevant to support UI
for configuring notification sounds.
emojiset_choices:
description: |
Array of dictionaries where each dictionary describes an emoji set
supported by this version of the Zulip server.
Only relevant to clients with configuration UI for choosing an emoji set;
the currently selected emoji set is available in the `emojiset` key.
See [PATCH /settings](/api/update-settings) for details on
the meaning of this setting.
type: array
items:
type: object
description: |
Object describing a emoji set.
additionalProperties: false
properties:
key:
type: string
description: |
The key or the name of the emoji set which will be the value
of `emojiset` if this emoji set is chosen.
text:
type: string
description: |
The text describing the emoji set.
send_private_typing_notifications:
type: boolean
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
private messages.
**Changes**: New in Zulip 5.0 (feature level 105).
send_stream_typing_notifications:
type: boolean
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
stream messages.
**Changes**: New in Zulip 5.0 (feature level 105).
send_read_receipts:
type: boolean
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
realm_users:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
A array of dictionaries where each entry describes a user
whose account has not been deactivated. Note that unlike
the usual User dictionary, this does not contain the `is_active`
key, as all the users present in this array have active accounts.
See also `cross_realm_bots` and `realm_non_active_users`.
items:
$ref: "#/components/schemas/User"
realm_non_active_users:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
A array of dictionaries where each entry describes a user
whose account has been deactivated. Note that unlike
the usual User dictionary this does not contain the `is_active`
key as all the users present in this array have deactivated
accounts.
items:
$ref: "#/components/schemas/User"
avatar_source:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The avatar data source type for the current user.
Value values are `G` (gravatar) and `U` (uploaded by user).
avatar_url_medium:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The avatar URL for the current user at 500x500 resolution, appropriate
for use in settings UI showing the user's avatar.
avatar_url:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The URL of the avatar for the current user at 100x100
resolution. See also `avatar_url_medium`.
can_create_streams:
type: boolean
deprecated: true
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create at least one type
of stream with the organization's [stream creation
policy](/help/configure-who-can-create-streams). Its value will
always equal `can_create_public_streams || can_create_private_streams`.
**Changes**: Deprecated in Zulip 5.0 (feature level 102), when
the new `create_private_stream_policy` and
`create_public_stream_policy` properties introduced the
possibility that a user could only create one type of stream.
This field will be removed in a future release.
can_create_public_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create public streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
**Changes**: New in Zulip 5.0 (feature level 102). In older
versions, the deprecated `can_create_streams` property should be
used to determine whether the user can create public streams.
can_create_private_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create private streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
**Changes**: New in Zulip 5.0 (feature level 102). In older
versions, the deprecated `can_create_streams` property should be
used to determine whether the user can create private streams.
can_create_web_public_streams:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to create public streams with
the organization's [stream creation policy](/help/configure-who-can-create-streams).
Note that this will be false if the Zulip server does not have the
`WEB_PUBLIC_STREAMS_ENABLED` setting enabled or if the organization has
not enabled the `enable_spectator_access` realm setting.
**Changes**: New in Zulip 5.0 (feature level 103).
can_subscribe_other_users:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is allowed to subscribe other users to streams with
the organization's [streams policy](/help/configure-who-can-invite-to-streams).
can_invite_others_to_realm:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user [is allowed to invite others][who-can-send-invitations]
to the organization.
**Changes**: New in Zulip 4.0 (feature level 51).
[who-can-send-invitations]: /help/restrict-account-creation#change-who-can-send-invitations
is_admin:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization administrator](/api/roles-and-permissions).
is_owner:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization owner](/api/roles-and-permissions).
is_billing_admin:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
is_moderator:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is an [organization moderator](/api/roles-and-permissions).
**Changes**: New in Zulip 4.0 (feature level 60).
is_guest:
type: boolean
description: |
Present if `realm_user` is present in `fetch_event_types`.
Whether the current user is a [guest user](/api/roles-and-permissions).
enter_sends:
deprecated: true
type: boolean
description: |
Present if `update_display_settings` is present in `fetch_event_types`
and only for clients that did not include `user_settings_object` in
their client_capabilities` when registering the event queue.
Whether the user setting for [sending on pressing Enter](/help/enable-enter-to-send)
in the compose box is enabled.
**Changes**: Deprecated in Zulip 5.0 (feature level 89). Clients
connecting to newer servers should declare the `user_settings_object`
client capability and process the `user_settings` event type instead.
Prior to Zulip 5.0 (feature level 84) this field was present
in response if 'realm_user' was present in `fetch_event_types`, not
`update_display_settings`.
user_id:
type: integer
description: |
Present if `realm_user` is present in `fetch_event_types`.
The unique ID for the current user.
email:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The Zulip display email address for the current user. See also
`delivery_email`; these may be the same or different depending
on the organization's `email_address_visibility` policy.
delivery_email:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The user's email address, appropriate for UI for changing
the user's email address. See also `email`.
full_name:
type: string
description: |
Present if `realm_user` is present in `fetch_event_types`.
The full name of the current user.
cross_realm_bots:
type: array
description: |
Present if `realm_user` is present in `fetch_event_types`.
Array of dictionaries where each dictionary contains details of
a single cross realm bot. Cross-realm bots are special system bot accounts
like Notification Bot.
Most clients will want to combine this with `realm_users` in many
contexts.
items:
allOf:
- $ref: "#/components/schemas/UserBase"
- additionalProperties: false
properties:
user_id: {}
delivery_email: {}
email: {}
full_name: {}
date_joined: {}
is_active: {}
is_owner: {}
is_admin: {}
is_guest: {}
is_billing_admin: {}
is_bot: {}
# Referenced schema properties are rendered before any
# non-referenced properties in the API documentation, so
# `is_system_bot` appears last instead of in this order.
# General practice should be to define properties in the
# same order that they are rendered in the API documentation.
# TODO: See if we can match the order of properties as
# listed here when rendered in the API documentation.
is_system_bot:
type: boolean
description: |
Whether the user is a system bot. System bots are special
bot user accounts that are managed by the system, rather than
the organization's administrators.
**Changes**: This field was called `is_cross_realm_bot`
before Zulip 5.0 (feature level 83).
bot_type:
nullable: true
bot_owner_id:
nullable: true
role: {}
timezone: {}
avatar_url:
nullable: true
avatar_version: {}
profile_data: {}
example:
{
"last_event_id": -1,
"msg": "",
"queue_id": "1517975029:0",
"realm_emoji":
{
"1":
{
"author_id": 5,
"deactivated": false,
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png",
},
"2":
{
"author_id": 3,
"deactivated": false,
"id": "2",
"name": "animated_img",
"source_url": "/user_avatars/1/emoji/images/animated_img.gif",
"still_url": "/user_avatars/1/emoji/images/still/animated_img.png",
},
},
"result": "success",
"zulip_feature_level": 2,
"zulip_version": "5.0-dev-1650-gc3fd37755f",
"zulip_merge_base": "5.0-dev-1646-gea6b21cd8c",
}
/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
response, for two reasons:
* This endpoint has evolved over time, so responses from older Zulip servers
might be missing some keys (in which case a client should assume the
appropriate default).
* If a `/server_settings` request is made to the root domain of a
multi-subdomain server, like the root domain of zulip.com, the settings
that are realm-specific are not known and thus not provided.
description: |
Fetch global settings for a Zulip server.
`GET {{ api_url }}/v1/server_settings`
**Note:** this endpoint does not require any authentication at all, and you can use it to check:
- If this is a Zulip server, and if so, what version of Zulip it's running.
- What a Zulip client (e.g. a mobile app or
[zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to
know in order to display a login prompt for the server (e.g. what
authentication methods are available).
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
description: |
A typical successful JSON response for a single-organization server may look like:
properties:
result: {}
msg: {}
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, 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 Azure Active Directory account.
type: boolean
gitlab:
description: |
Whether the user can authenticate using their GitLab account.
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
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.
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.
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. 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_verson` 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 enabled.
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
description: |
The organization's canonical URL.
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 streams](/help/public-access-option) and
at least one web-public stream on the server currently
exists. Clients that support viewing content
in web-public streams 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_name": "Zulip Dev",
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
"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/landing-page/logos/googl_e-icon.png",
"login_url": "/accounts/login/social/google",
"signup_url": "/accounts/register/social/google",
},
{
"name": "github",
"display_name": "GitHub",
"display_icon": "/static/images/landing-page/logos/github-icon.png",
"login_url": "/accounts/login/social/github",
"signup_url": "/accounts/register/social/github",
},
],
}
/settings:
patch:
operationId: update-settings
summary: Update settings
tags: ["users"]
description: |
This endpoint is used to edit the current user's settings.
`PATCH {{ api_url }}/v1/settings`
**Changes**: Prior to Zulip 5.0 (feature level 80), this
endpoint only supported the `full_name`, `email`,
`old_password`, and `new_password` parameters. Notification
settings were managed by `PATCH /settings/notifications`, and
all other settings by `PATCH /settings/display`.
The feature level 80 migration to merge these endpoints did not
change how request parameters are encoded. However, it did change
the handling of any invalid parameters present in a request
(see feature level 78 change below).
The `/settings/display` and `/settings/notifications`
endpoints are now deprecated aliases for this endpoint for
backwards-compatibility, and will be removed once clients have
migrated to use this endpoint.
**Changes**: Prior to Zulip 5.0 (feature level 78),
the `/settings` endpoint indicated which parameters it had
processed by including in the response object `"key": value`
entries for values successfully changed by the request. That
was replaced by the more ergonomic
`ignored_parameters_unsupported` response parameter.
The `/settings/notifications` and `/settings/display` endpoints
also had this behavior before they became aliases of `/settings`
in Zulip 5.0 (see feature level 80 change above).
Before these changes, request parameters that were not supported
(or were unchanged) were silently ignored.
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- left_side_userlist
- emojiset
parameters:
- name: full_name
in: query
description: |
A new display name for the user.
schema:
type: string
example: NewName
- name: email
in: query
description: |
Asks the server to initiate a confirmation sequence to change the user's email
address to the indicated value. The user will need to demonstrate control of the
new email address by clicking a confirmation link sent to that address.
schema:
type: string
example: newname@example.com
- name: old_password
in: query
description: |
The user's old Zulip password (or LDAP password, if LDAP authentication is in use).
Required only when sending the `new_password` parameter.
schema:
type: string
example: old12345
- name: new_password
in: query
description: |
The user's new Zulip password (or LDAP password, if LDAP authentication is in use).
The `old_password` parameter must be included in the request.
schema:
type: string
example: new12345
- name: twenty_four_hour_time
in: query
description: |
Whether time should be [displayed in 24-hour notation](/help/change-the-time-format).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: dense_mode
in: query
description: |
This setting has no effect at present. It is reserved for use in controlling
the default font size in Zulip.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: starred_message_counts
in: query
description: |
Whether clients should display the [number of starred
messages](/help/star-a-message#display-the-number-of-starred-messages).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: fluid_layout_width
in: query
description: |
Whether to use the [maximum available screen width](/help/enable-full-width-display)
for the web app's center panel (message feed, recent topics) on wide screens.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: high_contrast_mode
in: query
description: |
This setting is reserved for use to control variations in Zulip's design
to help visually impaired users.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: color_scheme
in: query
description: |
Controls which [color theme](/help/dark-theme) to use.
- 1 - Automatic
- 2 - Dark theme
- 3 - Light theme
Automatic detection is implementing using the standard `prefers-color-scheme`
media query.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: enable_drafts_synchronization
in: query
description: |
A boolean parameter to control whether synchronizing drafts is enabled for
the user. When synchronization is disabled, all drafts stored in the server
will be automatically deleted from the server.
This does not do anything (like sending events) to delete local copies of
drafts stored in clients.
**Changes**: New in Zulip 5.0 (feature level 87).
schema:
type: boolean
example: true
- name: translate_emoticons
in: query
description: |
Whether to [translate emoticons to emoji](/help/enable-emoticon-translations)
in messages the user sends.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: display_emoji_reaction_users
in: query
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 total reactions are present with this setting enabled.
**Changes**: New in Zulip 6.0 (feature level 125).
schema:
type: boolean
example: false
- name: default_language
in: query
description: |
What [default language](/help/change-your-language) to use for the account.
This controls both the Zulip UI as well as email notifications sent to the user.
The value needs to be a standard language code that the Zulip server has
translation data for; for example, `"en"` for English or `"de"` for German.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
schema:
type: string
example: en
- name: default_view
in: query
description: |
The [default view](/help/configure-default-view) used when opening a new
Zulip web app window or hitting the `Esc` keyboard shortcut repeatedly.
- "recent_topics" - Recent topics view
- "all_messages" - All messages view
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
schema:
type: string
example: all_messages
- name: escape_navigates_to_default_view
in: query
description: |
Whether the escape key navigates to the
[configured default view](/help/configure-default-view).
**Changes**: New in Zulip 5.0 (feature level 107).
schema:
type: boolean
example: true
- name: left_side_userlist
in: query
description: |
Whether the users list on left sidebar in narrow windows.
This feature is not heavily used and is likely to be reworked.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: boolean
example: true
- name: emojiset
in: query
description: |
The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons),
used to display emoji to the user everywhere they appear in the UI.
- "google" - Google modern
- "google-blob" - Google classic
- "twitter" - Twitter
- "text" - Plain text
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
schema:
type: string
example: "google"
- name: demote_inactive_streams
in: query
description: |
Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar.
- 1 - Automatic
- 2 - Always
- 3 - Never
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: timezone
in: query
description: |
The user's [configured time zone](/help/change-your-timezone).
Time zone values supported by the server are served at
[/static/generated/timezones.json](/static/generated/timezones.json).
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/display` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 64).
schema:
type: string
example: "Asia/Kolkata"
- name: enable_stream_desktop_notifications
in: query
description: |
Enable visual desktop notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_email_notifications
in: query
description: |
Enable email notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_push_notifications
in: query
description: |
Enable mobile notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_stream_audible_notifications
in: query
description: |
Enable audible desktop notifications for stream messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: notification_sound
in: query
description: |
Notification sound name.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
Unnecessary JSON-encoding of this parameter was removed in Zulip 4.0 (feature level 63).
schema:
type: string
example: ding
- name: enable_desktop_notifications
in: query
description: |
Enable visual desktop notifications for private messages and @-mentions.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_sounds
in: query
description: |
Enable audible desktop notifications for private messages and
@-mentions.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: email_notifications_batching_period_seconds
in: query
description: |
The duration (in seconds) for which the server should wait to batch
email notifications before sending them.
**Changes**: New in Zulip 5.0 (feature level 82)
schema:
type: integer
example: 120
- name: enable_offline_email_notifications
in: query
description: |
Enable email notifications for private messages and @-mentions received
when the user is offline.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_offline_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is offline.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_online_push_notifications
in: query
description: |
Enable mobile notification for private messages and @-mentions received
when the user is online.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_digest_emails
in: query
description: |
Enable digest emails when the user is away.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_marketing_emails
in: query
description: |
Enable marketing emails. Has no function outside Zulip Cloud.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enable_login_emails
in: query
description: |
Enable email notifications for new logins to account.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: message_content_in_email_notifications
in: query
description: |
Include the message's content in email notifications for new messages.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: pm_content_in_desktop_notifications
in: query
description: |
Include content of private messages in desktop notifications.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: wildcard_mentions_notify
in: query
description: |
Whether wildcard mentions (E.g. @**all**) should send notifications
like a personal mention.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: desktop_icon_count_display
in: query
description: |
Unread count badge (appears in desktop sidebar and browser tab)
- 1 - All unreads
- 2 - Private messages and mentions
- 3 - None
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: integer
enum:
- 1
- 2
- 3
example: 1
- name: realm_name_in_notifications
in: query
description: |
Include organization name in subject of message notification emails.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: presence_enabled
in: query
description: |
Display the presence status to other users when online.
**Changes**: Before Zulip 5.0 (feature level 80), this setting was managed by
the `PATCH /settings/notifications` endpoint.
schema:
type: boolean
example: true
- name: enter_sends
in: query
description: |
Whether pressing Enter in the compose box sends a message
(or saves a message edit).
**Changes**: Before Zulip 5.0 (feature level 81), this setting was managed by
the `POST /users/me/enter-sends` endpoint, with the same parameter format.
schema:
type: boolean
example: true
- name: send_private_typing_notifications
in: query
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
private messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_stream_typing_notifications
in: query
description: |
Whether [typing notifications](/help/status-and-availability#typing-notifications) be sent when composing
stream messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
- name: send_read_receipts
in: query
description: |
Whether other users are allowed to see whether you've
read messages.
**Changes**: New in Zulip 5.0 (feature level 105).
schema:
type: boolean
example: true
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported:
$ref: "#/components/schemas/IgnoredParametersUnsupported"
example:
{
"ignored_parameters_unsupported": ["name", "password"],
"msg": "",
"result": "success",
}
/streams/{stream_id}/members:
get:
operationId: get-subscribers
summary: Get the subscribers of a stream
tags: ["streams"]
description: |
Get all users subscribed to a stream.
`Get {{ api_url }}/v1/streams/{stream_id}/members`
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
subscribers:
type: array
items:
type: integer
description: |
A list containing the IDs of all active users who are subscribed
to the stream.
example:
{"result": "success", "msg": "", "subscribers": [11, 26]}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error",
}
description: |
An example JSON response for when the requested stream does not exist,
or where the user does not have permission to access the target stream:
/streams:
get:
operationId: get-streams
summary: Get all streams
tags: ["streams"]
description: |
Get all streams that the user has access to.
`GET {{ api_url }}/v1/streams`
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ""
- type: include
parameters:
enum:
- include_public
description: |
You may pass in one or more of the parameters mentioned above
as URL query parameters, like so:
parameters:
- name: include_public
in: query
description: |
Include all public streams.
schema:
type: boolean
default: true
example: false
- name: include_web_public
in: query
description: |
Include all web-public streams.
schema:
type: boolean
default: false
example: true
- name: include_subscribed
in: query
description: |
Include all streams that the user is subscribed to.
schema:
type: boolean
default: true
example: false
- name: include_all_active
in: query
description: |
Include all active streams. The user must have administrative privileges
to use this parameter.
schema:
type: boolean
default: false
example: true
- name: include_default
in: query
description: |
Include all default streams for the user's realm.
schema:
type: boolean
default: false
example: true
- name: include_owner_subscribed
in: query
description: |
If the user is a bot, include all streams that the bot's owner is
subscribed to.
schema:
type: boolean
default: false
example: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
streams:
description: |
A list of `stream` objects with details on the requested streams.
type: array
items:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
is_default:
type: boolean
description: |
Whether the given stream is a
[default stream](/help/set-default-streams-for-new-users). Only
returned if the `include_default` parameter is `true`.
example:
{
"msg": "",
"result": "success",
"streams":
[
{
"description": "A Scandinavian country",
"invite_only": false,
"name": "Denmark",
"stream_id": 1,
},
{
"description": "Yet another Italian city",
"invite_only": false,
"name": "Rome",
"stream_id": 2,
},
{
"description": "Located in the United Kingdom",
"invite_only": false,
"name": "Scotland",
"stream_id": 3,
},
{
"description": "A northeastern Italian city",
"invite_only": false,
"name": "Venice",
"stream_id": 4,
},
{
"description": "A city in Italy",
"invite_only": false,
"name": "Verona",
"stream_id": 5,
},
{
"description": "New stream for testing",
"invite_only": false,
"name": "new stream",
"stream_id": 6,
},
],
}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error",
}
description: |
An example JSON response for when the user is not authorized to use the
`include_all_active` parameter (i.e. because they are not an organization
administrator):
/streams/{stream_id}:
delete:
operationId: archive-stream
summary: Archive a stream
tags: ["streams"]
description: |
[Archive the stream](/help/archive-a-stream) with the ID `stream_id`.
`DELETE {{ api_url }}/v1/streams/{stream_id}`
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error",
}
description: |
An example JSON response for when the supplied stream does not exist:
patch:
operationId: update-stream
summary: Update a stream
tags: ["streams"]
description: |
Configure the stream with the ID `stream_id`. This endpoint supports
an organization administrator editing any property of a stream,
including:
- Stream [name](/help/rename-a-stream) and [description](/help/change-the-stream-description)
- Stream [permissions](/help/stream-permissions), including
[privacy](/help/change-the-privacy-of-a-stream) and [who can
send](/help/stream-sending-policy).
`PATCH {{ api_url }}/v1/streams/{stream_id}`
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- new_name
- description
- is_private
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
- name: description
in: query
description: |
The new description for the stream. Limited Zulip markdown is allowed in this
field.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
schema:
type: string
example: "Discuss Italian history and travel destinations."
required: false
allowEmptyValue: true
- name: new_name
in: query
description: |
The new name for the stream.
**Changes**: Removed unnecessary JSON-encoding of this parameter in
Zulip 4.0 (feature level 64).
schema:
type: string
example: Italy
required: false
- name: is_private
in: query
description: |
Change whether the stream is a private stream.
schema:
type: boolean
example: true
required: false
- name: is_announcement_only
in: query
deprecated: true
description: |
Whether the stream is limited to announcements.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
schema:
type: boolean
example: true
required: false
- name: is_web_public
in: query
description: |
Change whether the stream is a web-public stream.
Note that creating web-public streams requires the
`WEB_PUBLIC_STREAMS_ENABLED` [server setting][server-settings]
to be enabled on the Zulip server in question, the organization
to have enabled the `enable_spectator_access` realm setting, and
the current use to have permission under the organization's
`create_web_public_stream_policy` realm setting.
[server-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
**Changes**: New in Zulip 5.0 (feature level 98).
schema:
type: boolean
example: true
required: false
- $ref: "#/components/parameters/StreamPostPolicy"
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
- $ref: "#/components/parameters/MessageRetentionDays"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream id",
"result": "error",
}
description: |
An example JSON response for when the supplied stream does not exist:
/streams/{stream_id}/delete_topic:
post:
operationId: delete-topic
summary: Delete a topic
tags: ["streams"]
description: |
Delete all messages in a topic.
`POST {{ api_url }}/v1/streams/{stream_id}/delete_topic`
Topics are a field on messages (not an independent
data structure), so deleting all the messages in the topic
deletes the topic from Zulip.
parameters:
- $ref: "#/components/parameters/StreamIdInPath"
- name: topic_name
in: query
description: |
The name of the topic to delete.
schema:
type: string
example: new coffee machine
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"result": "error",
"msg": "Must be an organization administrator",
"code": "UNAUTHORIZED_PRINCIPAL",
}
description: |
Error when the user does not have permission
to delete topics in this organization:
/typing:
post:
operationId: set-typing-status
summary: Set "typing" status
tags: ["users"]
description: |
Notify other users whether the current user is typing a message.
`POST {{ api_url }}/v1/typing`
Clients implementing Zulip's typing notifications protocol should work as follows:
- Send a request to this endpoint with `op="start"` when a user starts typing a message,
and also every `TYPING_STARTED_WAIT_PERIOD=10` seconds that the user continues to
actively type or otherwise interact with the compose UI (E.g. interacting with the
compose box emoji picker).
- Send a request to this endpoint with `op="stop"` when a user pauses using the
compose UI for at least `TYPING_STOPPED_WAIT_PERIOD=5` seconds or cancels
the compose action (if it had previously sent a "start" operation for that
compose action).
- Start displaying "Sender is typing" for a given conversation when the client
receives an `op="start"` event from the [events API](/api/get-events).
- Continue displaying "Sender is typing" until they receive an `op="stop"` event
from the [events API](/api/get-events) or `TYPING_STARTED_EXPIRY_PERIOD=15`
seconds have passed without a new `op="start"` event for that conversation.
- Clients that support displaying stream typing notifications (new in Zulip 4.0)
should indicate they support processing stream typing events via the
`stream_typing_notifications` in the `client_capabilities` parameter to `/register`.
This protocol is designed to allow the server-side typing notifications implementation
to be stateless while being resilient; network failures cannot result in a user being
incorrectly displayed as perpetually typing.
See
[the typing notification docs](https://zulip.readthedocs.io/en/latest/subsystems/typing-indicators.html)
for additional design details on Zulip's typing notifications protocol.
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- topic
parameters:
- name: type
in: query
description: |
Type of the message being composed.
schema:
type: string
enum:
- private
- stream
default: private
example: private
- name: op
in: query
description: |
Whether the user has started (`start`) or stopped (`stop`) to type.
schema:
type: string
enum:
- start
- stop
example: start
required: true
- name: to
in: query
description: |
For 'private' type it is the user_ids of the recipients of the message being typed.
Send a JSON-encoded list of user_ids. (Use a list even if there is only one
recipient.)
For 'stream' type it is a single element list containing ID of stream in
which the message is being typed.
**Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded
list of email addresses. Support for the email address-based format was
removed in Zulip 3.0 (feature level 11).
content:
application/json:
schema:
type: array
items:
type: integer
example: [9, 10]
required: true
- name: topic
in: query
description: |
Topic to which message is being typed. Required for the 'stream' type.
Ignored in case of 'private' type.
schema:
type: string
example: typing notifications
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Cannot send to multiple streams",
"result": "error",
}
description: |
An example JSON error response for when user sends to multiple streams:
/user_groups/create:
post:
operationId: create-user-group
summary: Create a user group
tags: ["users"]
description: |
Create a new [user group](/help/user-groups).
`POST {{ api_url }}/v1/user_groups/create`
parameters:
- name: name
in: query
description: |
The name of the user group.
schema:
type: string
example: marketing
required: true
- name: description
in: query
description: |
The description of the user group.
schema:
type: string
example: The marketing team.
required: true
- name: members
in: query
description: |
An array containing the user IDs of the initial members for the
new user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [1, 2, 3, 4]
required: true
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"msg": "", "result": "success"}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"result": "error",
"code": "BAD_REQUEST",
"msg": "Invalid user ID: 500",
}
description: |
An example JSON error response for when the one of the users does not exist:
/user_groups/{user_group_id}/members:
post:
operationId: update-user-group-members
summary: Update user group members
tags: ["users"]
description: |
Update the members of a [user group](/help/user-groups).
`POST {{ api_url }}/v1/user_groups/{user_group_id}/members`
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- delete
parameters:
- $ref: "#/components/parameters/UserGroupId"
- name: delete
in: query
description: |
The list of user ids to be removed from the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [10]
required: false
- name: add
in: query
description: |
The list of user ids to be added to the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [12, 13]
required: false
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
get:
operationId: get-user-group-members
summary: Get user group members
tags: ["users"]
description: |
Get the members of a [user group](/help/user-groups).
`GET {{ api_url }}/v1/user_groups/{user_group_id}/members`
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- $ref: "#/components/parameters/DirectMemberOnly"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
members:
type: array
items:
type: integer
description: |
A list containing the user IDs of members of the user group.
example:
{"msg": "", "result": "success", "members": [10, 12]}
/user_groups/{user_group_id}:
patch:
operationId: update-user-group
summary: Update a user group
tags: ["users"]
description: |
Update the name or description of a [user group](/help/user-groups).
`PATCH {{ api_url }}/v1/user_groups/{user_group_id}`
parameters:
- $ref: "#/components/parameters/UserGroupId"
- name: name
in: query
description: |
The new name of the group.
schema:
type: string
example: marketing team
required: true
- name: description
in: query
description: |
The new description of the group.
schema:
type: string
example: The marketing team.
required: true
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error",
}
description: |
An example JSON response when the user group ID is invalid:
delete:
operationId: remove-user-group
summary: Delete a user group
tags: ["users"]
description: |
Delete a [user group](/help/user-groups).
`DELETE {{ api_url }}/v1/user_groups/{user_group_id}`
parameters:
- $ref: "#/components/parameters/UserGroupId"
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
- example: {"result": "success", "msg": ""}
"400":
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonError"
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid user group",
"result": "error",
}
description: |
An example JSON error response for an invalid user group id:
/user_groups:
get:
operationId: get-user-groups
summary: Get user groups
tags: ["users"]
description: |
{!api-members-only.md!}
Fetches all of the user groups in the organization.
`GET {{ api_url }}/v1/user_groups`
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
user_groups:
type: array
items:
type: object
additionalProperties: false
properties:
description:
type: string
description: |
The human-readable description of the user group.
id:
type: integer
description: |
The user group's integer id.
members:
type: array
description: |
The integer user IDs of the user group members.
items:
type: integer
subgroups:
type: array
description: |
The integer user group IDs of the subgroups.
**Changes**: New in Zulip 6.0 (feature level 127).
items:
type: integer
name:
type: string
description: |
User group name.
is_system_group:
type: boolean
description: |
Whether the user group is a system group which cannot be
modified by users.
**Changes**: New in Zulip 5.0 (feature level 93).
description: |
A list of `user_group` objects, which contain a `description`, a `name`,
their `id` and the list of members of the user group.
example:
{
"msg": "",
"result": "success",
"user_groups":
[
{
"description": "Characters of Hamlet",
"id": 1,
"name": "hamletcharacters",
"members": [3, 4],
"subgroups": [],
"is_system_group": false,
},
{
"description": "Moderators",
"id": 2,
"name": "other users",
"members": [1, 2],
"subgroups": [1, 2],
"is_system_group": true,
},
],
}
/user_groups/{user_group_id}/subgroups:
post:
operationId: update-user-group-subgroups
summary: Update subgroups of a user group
tags: ["users"]
description: |
Update the subgroups of a [user group](/help/user-groups).
`POST {{ api_url }}/v1/user_groups/{user_group_id}/subgroups`
**Changes**: New in Zulip 6.0 (feature level 127).
x-curl-examples-parameters:
oneOf:
- type: exclude
parameters:
enum:
- delete
parameters:
- $ref: "#/components/parameters/UserGroupId"
- name: delete
in: query
description: |
The list of user group ids to be removed from the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [10]
required: false
- name: add
in: query
description: |
The list of user group ids to be added to the user group.
content:
application/json:
schema:
type: array
items:
type: integer
example: [1, 2]
required: false
responses:
"200":
$ref: "#/components/responses/SimpleSuccess"
get:
operationId: get-user-group-subgroups
summary: Get subgroups of the user group
tags: ["users"]
description: |
Get the subgroups of a [user group](/help/user-groups).
`GET {{ api_url }}/v1/user_groups/{user_group_id}/subgroups`
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- name: direct_subgroup_only
in: query
description: |
Whether to consider only direct subgroups of the user group
or subgroups of subgroups also.
schema:
type: boolean
default: false
example: true
required: false
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
subgroups:
type: array
items:
type: integer
description: |
A list containing the IDs of subgroups of the user group.
example:
{"msg": "", "result": "success", "subgroups": [2, 3]}
/user_groups/{user_group_id}/members/{user_id}:
get:
operationId: get-is-user-group-member
summary: Get user group membership status
tags: ["users"]
description: |
Check whether a user is member of user group.
`GET {{ api_url }}/v1/user_groups/{user_group_id}/members/{user_id}`
**Changes**: New in Zulip 6.0 (feature level 127).
parameters:
- $ref: "#/components/parameters/UserGroupId"
- $ref: "#/components/parameters/UserId"
- $ref: "#/components/parameters/DirectMemberOnly"
responses:
"200":
description: Success
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
is_user_group_member:
type: boolean
description: |
Whether the user is member of user group.
example:
{
"msg": "",
"result": "success",
"is_user_group_member": false,
}
/real-time:
# This entry is a hack; it exists to give us a place to put the text
# documenting the parameters for call_on_each_event and friends.
post:
tags: ["real_time_events"]
description: |
(Ignored)
parameters:
- $ref: "#/components/parameters/Event_types"
- $ref: "#/components/parameters/Narrow"
- $ref: "#/components/parameters/AllPublicStreams"
security:
- basicAuth: []
responses:
# Makeshift response for this hack entry.
"200":
description: Success
/rest-error-handling:
post:
operationId: rest-error-handling
summary: Error handling
tags: ["real_time_events"]
description: |
Common error to many endpoints
responses:
"400":
description: |
Bad request.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/InvalidApiKeyError"
- $ref: "#/components/schemas/MissingArgumentError"
- $ref: "#/components/schemas/UserNotAuthorizedError"
"401":
description: |
Unauthorized.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/UserDeactivatedError"
- $ref: "#/components/schemas/RealmDeactivatedError"
"429":
description: |
Rate limit exceeded.
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/RateLimitedError"
/zulip-outgoing-webhook:
post:
operationId: zulip-outgoing-webhooks
summary: Outgoing webhooks
tags: ["webhooks"]
description: |
Outgoing webhooks allow you to build or set up Zulip integrations which are
notified when certain types of messages are sent in Zulip.
responses:
"200":
description: |
Success
content:
application/json:
schema:
type: object
additionalProperties: false
description: |
This is an example of the JSON payload that the Zulip server will `POST`
to your server:
properties:
bot_email:
type: string
description: |
Email of the bot user.
bot_full_name:
type: string
description: |
The full name of the bot user.
data:
type: string
description: |
The message content, in raw Markdown format (not rendered to HTML).
trigger:
type: string
description: |
What aspect of the message triggered the outgoing webhook notification.
Possible values include `private_message` and `mention`.
token:
type: string
description: |
A string of alphanumeric characters that can be used to authenticate the
webhook request (each bot user uses a fixed token). You can get the token used by a given outgoing webhook bot
in the `zuliprc` file downloaded when creating the bot.
message:
description: |
A dictionary containing details on the message that triggered the
outgoing webhook, in the format used by [`GET /messages`](/api/get-messages).
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
rendered_content:
type: string
description: |
The content/body of the message rendered in HTML.
example:
{
"data": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
"trigger": "mention",
"token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0",
"message":
{
"subject": "Verona2",
"sender_email": "iago@zulip.com",
"timestamp": 1527876931,
"client": "website",
"submessages": [],
"recipient_id": 20,
"topic_links": [],
"sender_full_name": "Iago",
"avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1",
"rendered_content": "<p><span class=\"user-mention\" data-user-id=\"25\">@Outgoing webhook test</span> Zulip is the world\u2019s most productive group chat!</p>",
"sender_id": 5,
"stream_id": 5,
"content": "@**Outgoing webhook test** Zulip is the world\u2019s most productive group chat!",
"display_recipient": "Verona",
"type": "stream",
"id": 112,
"is_me_message": false,
"reactions": [],
"sender_realm_str": "zulip",
},
"bot_email": "outgoing-bot@localhost",
"bot_full_name": "Outgoing webhook test",
}
/calls/bigbluebutton/create:
get:
tags: ["streams"]
operationId: create-big-blue-button-video-call
summary: Create BigBlueButton video call
description: |
Create a video call URL for a BigBlueButton video call.
Requires BigBlueButton to be configured on the Zulip server.
parameters:
- in: query
name: meeting_name
schema:
type: string
required: true
description: |
Title to use for the BigBlueButton meeting.
A good choice is something like "{stream_name} meeting".
responses:
"200":
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- $ref: "#/components/schemas/SuccessDescription"
- additionalProperties: false
properties:
result: {}
msg: {}
url:
description: |
The URL for the BigBlueButton video call.
type: string
example: "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&name=%22your_meeting_name%22&checksum=%22somechecksum%22"
example:
{
"msg": "",
"result": "success",
"url": "/calls/bigbluebutton/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22",
}
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: |
Basic authentication, with the user's email as the username, and the API
key as the password. The API key can be fetched using the
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
schemas:
IgnoredParametersUnsupported:
type: array
items:
type: string
description: |
An array of any parameters sent in the request that are not
supported by the endpoint. While this can be expected, e.g. when sending
both current and legacy names for a parameter to a Zulip server of
unknown version, this often indicates either a bug in the client
implementation or an attempt to configure a new feature while
connected to an older Zulip server that does not support said feature.
**Changes**: Added to `POST /users/me/subscriptions/properties` in
Zulip 5.0 (feature level 111).
Added to `PATCH /realm/user_settings_defaults` in Zulip 5.0 (feature level 96).
Introduced in `PATCH /settings` in Zulip 5.0 (feature level 78).
EventIdSchema:
type: integer
description: |
The ID of the event. Events appear in increasing order but may not be consecutive.
EventTypeSchema:
type: string
description: |
The event's type, relevant both for client-side dispatch and server-side
filtering by event type in [POST /register](/api/register-queue).
Attachments:
type: object
description: |
Dictionary containing details of a file uploaded by a user.
additionalProperties: false
properties:
id:
type: integer
description: |
The unique ID for the attachment.
name:
type: string
description: |
Name of the uploaded file.
path_id:
type: string
description: |
A representation of the path of the file within the
repository of user-uploaded files. If the `path_id` of a
file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be:
`{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`.
size:
type: integer
description: |
Size of the file in bytes.
create_time:
type: integer
description: |
Time when the attachment was uploaded as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 2.2 (feature level 22). This field was
previously a floating point number.
messages:
type: array
description: |
Contains basic details on any Zulip messages that have been
sent referencing this [uploaded file](/api/upload-file).
This includes messages sent by any user in the Zulip
organization who sent a message containing a link to the
uploaded file.
items:
type: object
additionalProperties: false
properties:
date_sent:
type: integer
description: |
Time when the message was sent as a UNIX timestamp
multiplied by 1000 (matching the format of getTime() in JavaScript).
**Changes**: Changed in Zulip 2.2 (feature level 22). This
field was previously strangely called `name` and was a floating
point number.
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
BasicStream:
allOf:
- $ref: "#/components/schemas/BasicStreamBase"
- additionalProperties: false
properties:
stream_id: {}
name: {}
description: {}
date_created: {}
invite_only: {}
rendered_description: {}
is_web_public: {}
stream_post_policy: {}
message_retention_days:
nullable: true
history_public_to_subscribers: {}
first_message_id:
nullable: true
is_announcement_only: {}
BasicStreamBase:
type: object
description: |
Object containing basic details about the stream.
properties:
stream_id:
type: integer
description: |
The unique ID of the stream.
name:
type: string
description: |
The name of the stream.
description:
type: string
description: |
The short description of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
rendered_description:
type: string
description: |
The short description of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
stream_post_policy:
type: integer
description: |
[Policy][permission-level] for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only [full members][calc-full-member] can post.
- 4 => Only moderators can post.
**Changes**: New in Zulip 3.0, replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). There are two special values:
- `null`, the default, means the stream will inherit the organization
level setting.
- `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
nullable: true
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether the given stream is announcement only or not.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
BasicBot:
allOf:
- $ref: "#/components/schemas/BasicBotBase"
- additionalProperties: false
properties:
user_id: {}
full_name: {}
api_key: {}
default_sending_stream:
nullable: true
default_events_register_stream:
nullable: true
default_all_public_streams: {}
avatar_url: {}
owner_id:
nullable: true
services:
items: {} # https://github.com/p1c2u/openapi-core/issues/380
BasicBotBase:
type: object
properties:
user_id:
type: integer
description: |
The user id of the bot.
full_name:
type: string
description: |
The full name of the bot.
api_key:
type: string
description: |
The API key of the bot which it uses to make API requests.
default_sending_stream:
type: string
nullable: true
description: |
The default sending stream of the bot. Null if the bot doesn't
have a default sending stream.
default_events_register_stream:
type: string
nullable: true
description: |
The default stream for which the bot receives events/register data. Null if
the bot doesn't have such a default stream.
default_all_public_streams:
type: boolean
description: |
Whether the bot can send messages to all streams by default.
avatar_url:
type: string
description: |
The URL of the bot's avatar.
owner_id:
type: integer
nullable: true
description: |
The user id of the bot's owner.
Null if the bot has no owner.
services:
type: array
description: |
The "Services" array contains extra configuration fields only relevant
for Outgoing webhook bots and Embedded bots. It is always a single-element
array.
We consider this part of the Zulip API to be unstable; it is used only for
UI elements for administering bots and is likely to change.
items:
description: |
Object containing details extra details. Which fields appear depend
on the type of bot.
oneOf:
- type: object
additionalProperties: false
description: |
When the bot is an outgoing webhook bot.
properties:
base_url:
type: string
description: |
The URL the outgoing webhook is configured to post to.
token:
type: string
description: |
A unique token that the third-party service can use to confirm
that the request is indeed coming from Zulip.
interface:
type: integer
description: |
Integer indicating what format requests are posted in:
- 1 = Zulip's native outgoing webhook format.
- 2 = Emulate the Slack outgoing webhook format.
- type: object
additionalProperties: false
description: |
When the bot is an embedded bot.
properties:
service_name:
type: string
description: |
The name of the bot.
config_data:
$ref: "#/components/schemas/Config"
Bot:
allOf:
- $ref: "#/components/schemas/BasicBotBase"
- description: |
Object containing details of a bot.
additionalProperties: false
properties:
user_id: {}
full_name: {}
api_key: {}
default_sending_stream:
nullable: true
default_events_register_stream:
nullable: true
default_all_public_streams: {}
avatar_url: {}
owner_id:
nullable: true
services:
items: {} # https://github.com/p1c2u/openapi-core/issues/380
email:
type: string
description: |
The email of the bot.
bot_type:
type: integer
nullable: true
description: |
An integer describing the type of bot:
- `1` for a `Generic` bot.
- `2` for an `Incoming webhook` bot.
- `3` for an `Outgoing webhook` bot.
- `4` for an `Embedded` bot.
is_active:
type: boolean
description: |
A boolean describing whether the user account has been deactivated.
Config:
type: object
description: |
A "string: string" dictionary which describes the configuration
for the embedded bot (usually details like API keys).
additionalProperties:
description: |
String describing the config data.
type: string
CustomProfileField:
type: object
additionalProperties: false
description: |
Dictionary containing the details of a custom profile field configured
for this organization.
properties:
id:
type: integer
description: |
The ID of the custom profile field. This will be referenced in custom
the profile fields section of user objects.
type:
type: integer
description: |
An integer indicating the type of the custom profile field, which determines
how it is configured and displayed to users.
See the [Add custom profile fields](/help/add-custom-profile-fields)
article for details on what each type means.
- **1**: Short text
- **2**: Long text
- **3**: List of options
- **4**: Date picker
- **5**: Link
- **6**: Person picker
- **7**: External account
order:
type: integer
description: |
Custom profile fields are displayed in both settings UI and
UI showing users' profiles in increasing `order`.
name:
type: string
description: |
The name of the custom profile field.
hint:
type: string
description: |
The help text to be displayed for the custom profile field in user-facing
settings UI for configuring custom profile fields.
field_data:
type: string
description: |
Field types 3 (List of options) and 7 (External account) support storing
additional configuration for the field type in the `field_data` attribute.
For field type 3 (List of options), this attribute is a JSON dictionary
defining the choices and the order they will be displayed in the
dropdown UI for individual users to select an option.
The interface for field type 7 is not yet stabilized.
Hotspot:
type: object
additionalProperties: false
description: |
Dictionary containing details of a single hotspot.
properties:
delay:
type: number
description: |
The delay after which the user should be shown the hotspot.
name:
type: string
description: |
The name of the hotspot.
title:
type: string
description: |
The title of the hotspot, as will be displayed to the user.
description:
type: string
description: |
The description of the hotspot, as will be displayed to the
user.
RealmEmoji:
type: object
additionalProperties: false
description: |
`{emoji_id}`: Object containing details about the emoji with
the specified ID. It has the following properties:
properties:
id:
type: string
description: |
The ID for this emoji, same as the object's key.
name:
type: string
description: |
The user-friendly name for this emoji. Users in the organization
can use this emoji by writing this name between colons (`:name :`).
source_url:
type: string
description: |
The path relative to the organization's URL where the
emoji's image can be found.
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 and `author` object with an `id` field.
RealmDomain:
type: object
additionalProperties: false
description: |
Object containing details of the newly added domain.
properties:
domain:
type: string
description: |
The new allowed domain.
allow_subdomains:
type: boolean
description: |
Whether subdomains are allowed for this domain.
RealmPlayground:
type: object
additionalProperties: false
description: |
Object containing details about a realm playground.
properties:
id:
type: integer
description: |
The unique ID for the realm playground.
name:
type: string
description: |
The user-visible display name of the playground. Clients
should display this in UI for picking which playground to
open a code block in, to differentiate between multiple
configured playground options for a given pygments
language.
**Changes**: New in Zulip 4.0 (feature level 49).
pygments_language:
type: string
description: |
The name of the Pygments language lexer for that
programming language.
url_prefix:
type: string
description: |
The url prefix for the playground.
RealmExport:
type: object
additionalProperties: false
description: |
Object containing details about a realm export.
properties:
id:
type: integer
description: |
The id of the export.
acting_user_id:
type: integer
description: |
The id of the user who did the export.
export_time:
type: number
description: |
The UNIX timestamp of when the export was made.
deleted_timestamp:
type: number
nullable: true
description: |
The timestamp of when the export was deleted.
Null if it wasn't.
failed_timestamp:
type: number
nullable: true
description: |
The timestamp of when the export failed.
Null if it didn't.
export_url:
type: string
nullable: true
description: |
The URL of the export. `null` if there's no URL.
pending:
type: boolean
description: |
Whether the export is pending or not.
UserGroup:
type: object
additionalProperties: false
description: |
Object containing the user group's attributes.
properties:
name:
type: string
description: |
The name of the user group.
description:
type: string
description: |
The description of the user group.
members:
type: array
items:
type: integer
description: |
Array containing the id of the users who are
members of this user group.
subgroups:
type: array
items:
type: integer
description: |
Array containing the id of the subgroups of this
user group.
**Changes**: New in Zulip 6.0 (feature level 127).
id:
type: integer
description: |
The ID of the user group.
is_system_group:
type: boolean
description: |
Whether the user group is a system group which cannot be
directly modified by users.
**Changes**: New in Zulip 5.0 (feature level 93).
Subscriptions:
type: object
additionalProperties: false
properties:
stream_id:
type: integer
description: |
The unique ID of a stream.
name:
type: string
description: |
The name of a stream.
description:
type: string
description: |
The [description](/help/change-the-stream-description) of the stream in text/markdown format,
intended to be used to prepopulate UI for editing a stream's
description.
See also `rendered_description`.
rendered_description:
type: string
description: |
The [description](/help/change-the-stream-description) of the stream rendered as HTML, intended to
be used when displaying the stream description in a UI.
One should use the standard Zulip rendered_markdown CSS when
displaying this content so that emoji, LaTeX, and other syntax
work correctly. And any client-side security logic for
user-generated message content should be applied when displaying
this HTML as though it were the body of a Zulip message.
See also `description`.
date_created:
type: integer
description: |
The UNIX timestamp for when the stream was created, in UTC seconds.
**Changes**: New in Zulip 4.0 (feature level 30).
invite_only:
type: boolean
description: |
Specifies whether the stream is private or not.
Only people who have been invited can access a private stream.
# TODO: This subscribers item should probably be declared optional more
# explicitly in the OpenAPI format?
subscribers:
type: array
items:
type: integer
description: |
A list of user IDs of users who are also subscribed
to a given stream. Included only if `include_subscribers` is `true`.
desktop_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether desktop notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_desktop_notifications, for
this stream.
email_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether email notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_email_notifications, for
this stream.
wildcard_mentions_notify:
type: boolean
nullable: true
description: |
A boolean specifying whether wildcard mentions
trigger notifications as though they were personal
mentions in this stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, wildcard_mentions_notify, for
this stream.
push_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether push notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_push_notifications, for
this stream.
audible_notifications:
type: boolean
nullable: true
description: |
A boolean specifying whether audible notifications
are enabled for the given stream.
A null value means the value of this setting
should be inherited from the user-level default
setting, enable_stream_audible_notifications, for
this stream.
pin_to_top:
type: boolean
description: |
A boolean specifying whether the given stream has been pinned
to the top.
email_address:
type: string
description: |
Email address of the given stream, used for
[sending emails to the stream](/help/message-a-stream-by-email).
is_muted:
type: boolean
description: |
Whether the user has muted the stream. Muted streams do
not count towards your total unread count and do not show up in
`All messages` view (previously known as `Home` view).
**Changes**: Prior to Zulip 2.1, this feature was
represented by the more confusingly named `in_home_view` (with the
opposite value, `in_home_view=!is_muted`).
in_home_view:
type: boolean
deprecated: true
description: |
Legacy property for if the given stream is muted, with inverted meeting.
**Deprecated**; clients should use is_muted where available.
is_announcement_only:
type: boolean
deprecated: true
description: |
Whether only organization administrators can post to the stream.
**Changes**: Deprecated in Zulip 3.0 (feature level 1), use
`stream_post_policy` instead.
is_web_public:
type: boolean
description: |
Whether the stream has been configured to allow unauthenticated
access to its message history from the web.
role:
type: integer
enum:
- 20
- 50
description: |
The user's role within the stream (distinct from the user's
[organization-level role](/help/roles-and-permissions)).
Valid values are:
- 20 => Stream administrator.
- 50 => Subscriber.
**Changes**: New in Zulip 4.0 (feature level 31).
color:
type: string
description: |
The user's personal color for the stream.
stream_post_policy:
type: integer
description: |
[Policy][permission-level] for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only [full members][calc-full-member] can post.
- 4 => Only moderators can post.
**Changes**: New in Zulip 3.0, replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
message_retention_days:
type: integer
nullable: true
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). There are two special values:
- `null`, the default, means the stream will inherit the organization
level setting.
- `-1` encodes retaining messages in this stream forever.
**Changes**: New in Zulip 3.0 (feature level 17).
history_public_to_subscribers:
type: boolean
description: |
Whether the history of the stream is public to its subscribers.
Currently always true for public streams (i.e. invite_only=False implies
history_public_to_subscribers=True), but clients should not make that
assumption, as we may change that behavior in the future.
first_message_id:
type: integer
nullable: true
description: |
The id of the first message in the stream.
Intended to help clients determine whether they need to display
UI like the "more topics" widget that would suggest the stream
has older history that can be accessed.
Null is used for streams with no message history.
stream_weekly_traffic:
type: integer
nullable: true
description: |
The average number of messages sent to the stream in recent weeks,
rounded to the nearest integer.
Null means the stream was recently created and there is
insufficient data to estimate the average traffic.
DefaultStreamGroup:
type: object
description: |
Dictionary containing details of a default stream
group.
additionalProperties: false
properties:
name:
type: string
description: |
Name of the default stream group.
description:
type: string
description: |
Description of the default stream group.
id:
type: integer
description: |
id of the default stream group.
streams:
type: array
description: |
Array containing details about the streams
in the default stream group.
items:
$ref: "#/components/schemas/BasicStream"
EmojiReaction:
allOf:
- $ref: "#/components/schemas/EmojiReactionBase"
- additionalProperties: false
properties:
emoji_code: {}
emoji_name: {}
reaction_type: {}
user_id: {}
user: {}
EmojiBase:
type: object
properties:
emoji_name:
type: string
description: |
Name of the emoji.
emoji_code:
type: string
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
reaction_type:
type: string
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
Must be one of the following values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
EmojiReactionBase:
allOf:
- $ref: "#/components/schemas/EmojiBase"
- properties:
user_id:
type: integer
description: |
The ID of the user who added the reaction.
**Changes**: New in Zulip 3.0 (feature level 2). The `user`
object is deprecated and will be removed in the future.
user:
type: object
additionalProperties: false
deprecated: true
description: |
**Deprecated** and to be removed in a future release
once core clients have migrated to use the adjacent
`user_id` field introduced in Zulip 3.0 (feature level
2). Clients supporting older Zulip server versions
should just use the user ID below as they would the
`user_id` field.
Dictionary with data on the user who added the
reaction, including the user ID as the `id`
field. Note that reactions data received from the
[events API](/api/get-events) has a slightly different
`user` dictionary format, with the user ID field
called `user_id` instead.
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
MessagesEvent:
allOf:
- $ref: "#/components/schemas/MessagesBase"
- additionalProperties: false
properties:
avatar_url:
nullable: true
client: {}
content: {}
content_type: {}
display_recipient: {}
edit_history: {}
id: {}
is_me_message: {}
last_edit_timestamp: {}
reactions: {}
recipient_id: {}
sender_email: {}
sender_full_name: {}
sender_id: {}
sender_realm_str: {}
stream_id: {}
subject: {}
submessages: {}
timestamp: {}
topic_links: {}
type: {}
MessagesBase:
type: object
description: |
Object containing details of the message.
properties:
avatar_url:
type: string
nullable: true
description: |
The URL of the user's avatar. Can be null only if client_gravatar was passed,
which means that the user has not uploaded an avatar in Zulip, and the
client should compute the gravatar URL by hashing the
user's email address itself for this user.
client:
type: string
description: |
A Zulip "client" string, describing what Zulip client
sent the message.
content:
type: string
description: |
The content/body of the message.
content_type:
type: string
description: |
The HTTP `content_type` for the message content. This
will be `text/html` or `text/x-markdown`, depending on
whether `apply_markdown` was set.
display_recipient:
oneOf:
- type: string
- type: array
items:
type: object
additionalProperties: false
properties:
id:
type: integer
description: |
ID of the user.
email:
type: string
description: |
Email of the user.
full_name:
type: string
description: |
Full name of the user.
is_mirror_dummy:
type: boolean
description: |
Whether the user is a mirror dummy.
description: |
Data on the recipient of the message;
either the name of a stream or a dictionary containing basic data on
the users who received the message.
edit_history:
type: array
items:
type: object
additionalProperties: false
properties:
prev_content:
type: string
description: |
Only present if message's content was edited.
The content of the message immediately prior to this
edit event.
prev_rendered_content:
type: string
description: |
Only present if message's content was edited.
The rendered HTML representation of `prev_content`.
prev_rendered_content_version:
type: integer
description: |
Only present if message's content was edited.
The Markdown processor version number for the message
immediately prior to this edit event.
prev_stream:
type: integer
description: |
Only present if message's stream was edited.
The stream ID of the message immediately prior to this
edit event.
prev_topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately prior to this
edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
Previously, this field was called `prev_subject`;
clients are recommended to rename `prev_subject` to
`prev_topic` if present for compatibility with
older Zulip servers.
stream:
type: integer
description: |
Only present if message's stream was edited.
The ID of the stream containing the message
immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
timestamp:
type: integer
description: |
The UNIX timestamp for the edit.
topic:
type: string
description: |
Only present if message's topic was edited.
The topic of the message immediately after this edit event.
**Changes**: New in Zulip 5.0 (feature level 118).
user_id:
type: integer
nullable: true
description: |
The ID of the user that made the edit.
Will be null only for edit history
events predating March 2017.
Clients can display edit history events where this
is null as modified by either the sender (for content
edits) or an unknown user (for topic edits).
required:
- user_id
- timestamp
description: |
An array of objects, with each object documenting the
changes in a previous edit made to the the message,
ordered chronologically from most recent to least recent
edit.
Not present if the message has never been edited or if the realm has
[disabled viewing of message edit history][disable-edit-history].
Every object will contain `user_id` and `timestamp`.
The other fields are optional, and will be present or not
depending on whether the stream, topic, and/or message
content were modified in the edit event. For example, if
only the topic was edited, only `prev_topic` and `topic`
will be present in addition to `user_id` and `timestamp`.
[disable-edit-history]: /help/disable-message-edit-history
id:
type: integer
description: |
The unique message ID. Messages should always be
displayed sorted by ID.
is_me_message:
type: boolean
description: |
Whether the message is a [/me status message][status-messages]
[status-messages]: /help/format-your-message-using-markdown#status-messages
last_edit_timestamp:
type: integer
description: |
The UNIX timestamp for when the message was last edited,
in UTC seconds.
Not present if the message has never been edited.
reactions:
type: array
description: |
Data on any reactions to the message.
items:
$ref: "#/components/schemas/EmojiReaction"
recipient_id:
type: integer
description: |
A unique ID for the set of users receiving the
message (either a stream or group of users). Useful primarily
for hashing.
sender_email:
type: string
description: |
The Zulip display email address of the message's sender.
sender_full_name:
type: string
description: |
The full name of the message's sender.
sender_id:
type: integer
description: |
The user ID of the message's sender.
sender_realm_str:
type: string
description: |
A string identifier for the realm the sender is in. Unique only within
the context of a given Zulip server.
E.g. on `example.zulip.com`, this will be `example`.
stream_id:
type: integer
description: |
Only present for stream messages; the ID of the stream.
subject:
type: string
description: |
The `topic` of the message. Currently always `""` for private messages,
though this could change if Zulip adds support for topics in private
message conversations.
The field name is a legacy holdover from when topics were
called "subjects" and will eventually change.
submessages:
type: array
items:
type: string
description: |
Data used for certain experimental Zulip integrations.
timestamp:
type: integer
description: |
The UNIX timestamp for when the message was sent,
in UTC seconds.
topic_links:
type: array
items:
type: object
additionalProperties: false
properties:
text:
type: string
description: |
The original link text present in the topic.
url:
type: string
description: |
The expanded target url which the link points to.
description: |
Data on any links to be included in the `topic`
line (these are generated by [custom linkification
filters](/help/add-a-custom-linkifier) that match content in the
message's topic.)
**Changes**: This field contained a list of urls before
Zulip 4.0 (feature level 46).
New in Zulip 3.0 (feature level 1): Previously, this field was called
`subject_links`; clients are recommended to rename `subject_links` to `topic_links`
if present for compatibility with older Zulip servers.
type:
type: string
description: |
The type of the message: `stream` or `private`.
Presence:
type: object
description: |
`{client_name}`: Object containing the details of the user's
presence on a particular platform with the client's platform
name being the object key.
additionalProperties: false
properties:
client:
type: string
description: |
The client's platform name.
status:
type: string
enum:
- idle
- active
description: |
The status of the user on this client. It is either `idle`
or `active`.
timestamp:
type: integer
description: |
The UNIX timestamp of when this client sent the user's presence
to the server with the precision of a second.
pushable:
type: boolean
description: |
Whether the client is capable of showing mobile/push notifications
to the user.
Draft:
type: object
description: |
A dictionary for representing a message draft.
properties:
id:
type: integer
description: |
The unique ID of the draft. It will only used whenever the drafts are
fetched. This field should not be specified when the draft is being
created or edited.
type:
type: string
description: |
The type of the draft. Either unaddressed (empty string), "stream",
or "private" (for PMs and private group messages).
enum:
- ""
- stream
- private
to:
type: array
description: |
An array of the tentative target audience IDs. For "stream"
messages, this should contain exactly 1 ID, the ID of the
target stream. For private messages, this should be an array
of target user IDs. For unaddressed drafts, this is ignored,
and clients should send an empty array.
items:
type: integer
topic:
type: string
description: |
For stream message drafts, the tentative topic name. For private
or unaddressed messages, this will be ignored and should ideally
be the empty string. Should not contain null bytes.
content:
type: string
description: |
The body of the draft. Should not contain null bytes.
timestamp:
type: number
description: |
A Unix timestamp (seconds only) representing when the draft was
last edited. When creating a draft, this key need not be present
and it will be filled in automatically by the server.
example: 1595479019
additionalProperties: false
required:
- type
- to
- topic
- content
User:
allOf:
- $ref: "#/components/schemas/UserBase"
- additionalProperties: false
properties:
user_id: {}
delivery_email: {}
email: {}
full_name: {}
date_joined: {}
is_active: {}
is_owner: {}
is_admin: {}
is_guest: {}
is_billing_admin: {}
is_bot: {}
bot_type:
nullable: true
bot_owner_id:
nullable: true
role: {}
timezone: {}
avatar_url:
nullable: true
avatar_version: {}
profile_data: {}
UserBase:
type: object
description: |
A dictionary containing basic data on a given Zulip user.
properties:
user_id:
type: integer
description: |
The unique ID of the user.
delivery_email:
type: string
description: |
The user's real email address. This field is present only if
[email address visibility](/help/restrict-visibility-of-email-addresses) is
limited and you are an administrator with access to real email addresses
under the configured policy.
email:
type: string
description: |
The Zulip API email address of the user or bot.
If you do not have permission to view the email address of the target user,
this will be a fake email address that is usable for the Zulip API but nothing else.
full_name:
type: string
description: |
Full name of the user or bot, used for all display purposes.
date_joined:
type: string
description: |
The time the user account was created.
is_active:
type: boolean
description: |
A boolean specifying whether the user account has been deactivated.
is_owner:
type: boolean
description: |
A boolean specifying whether the user is an organization owner.
If true, `is_admin` will also be true.
**Changes**: New in Zulip 3.0 (feature level 8).
is_admin:
type: boolean
description: |
A boolean specifying whether the user is an organization administrator.
is_guest:
type: boolean
description: |
A boolean specifying whether the user is a guest user.
is_billing_admin:
type: boolean
description: |
A boolean specifying whether the user is a billing administrator.
**Changes**: New in Zulip 5.0 (feature level 73).
is_bot:
type: boolean
description: |
A boolean specifying whether the user is a bot or full account.
bot_type:
type: integer
nullable: true
description: |
An integer describing the type of bot:
- `null` if the user isn't a bot.
- `1` for a `Generic` bot.
- `2` for an `Incoming webhook` bot.
- `3` for an `Outgoing webhook` bot.
- `4` for an `Embedded` bot.
bot_owner_id:
type: integer
nullable: true
description: |
If the user is a bot (i.e. `is_bot` is `True`),
`bot_owner` is the user ID of the bot's owner (usually, whoever
created the bot).
Will be null for legacy bots that do not have an owner.
**Changes**: New in Zulip 3.0 (feature level
1). In previous versions, there was a `bot_owner` field
containing the email address of the bot's owner.
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: |
[Organization-level role](/api/roles-and-permissions) of the user.
Possible values are:
- Organization owner => 100
- Organization administrator => 200
- Organization moderator => 300
- Member => 400
- Guest => 600
**Changes**: New in Zulip 4.0 (feature level 59).
timezone:
type: string
description: |
The time zone of the user.
avatar_url:
type: string
nullable: true
description: |
URL for the user's avatar. Will be `null` if the `client_gravatar`
query parameter was set to `True` and the user's avatar is hosted by
the Gravatar provider (i.e. the user has never uploaded an avatar).
**Changes**: In Zulip 3.0 (feature level 18), if the client has the
`user_avatar_url_field_optional` capability, this will be missing at
the server's sole discretion.
avatar_version:
type: integer
description: |
Version for the user's avatar. Used for cache-busting requests
for the user's avatar. Clients generally shouldn't need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
profile_data:
$ref: "#/components/schemas/profile_data"
profile_data:
type: object
description: |
Only present if `is_bot` is false; bots can't have custom profile fields.
A dictionary containing custom profile field data for the user. Each entry
maps the integer ID of a custom profile field in the organization to a
dictionary containing the user's data for that field. Generally the data
includes just a single `value` key; for those custom profile fields
supporting Markdown, a `rendered_value` key will also be present.
additionalProperties:
type: object
additionalProperties: false
description: |
`{id}`: Object with data about what value user filled in the custom
profile field with id `id`.
properties:
value:
type: string
description: |
User's personal value for this custom profile field.
rendered_value:
type: string
description: |
The `value` rendered in HTML. Will only be present for
custom profile field types that support Markdown rendering.
This user-generated HTML content should be rendered
using the same CSS and client-side security protections
as are used for message content.
JsonResponseBase:
type: object
properties:
result:
type: string
SuccessDescription:
description: |
A typical successful JSON response may look like:
JsonSuccess:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
JsonSuccessBase:
allOf:
- $ref: "#/components/schemas/JsonResponseBase"
- required:
- result
- msg
properties:
result:
enum:
- success
msg:
type: string
example: {"msg": "", "result": "success"}
JsonError:
allOf:
- $ref: "#/components/schemas/JsonErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
JsonErrorBase:
allOf:
- $ref: "#/components/schemas/JsonResponseBase"
- required:
- result
- msg
properties:
result:
enum:
- error
msg:
type: string
ApiKeyResponse:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- required:
- api_key
- email
additionalProperties: false
properties:
result: {}
msg: {}
api_key:
type: string
description: |
The API key that can be used to authenticate as the requested user.
email:
type: string
description: |
The email address of the user who owns the API key
example:
{
"api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv",
"email": "iago@zulip.com",
"msg": "",
"result": "success",
}
CodedError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
CodedErrorBase:
allOf:
- $ref: "#/components/schemas/JsonErrorBase"
- properties:
result: {}
msg: {}
code:
type: string
description: |
A string that identifies the error.
BadEventQueueIdError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
queue_id:
type: string
description: |
The string that identifies the invalid event queue.
example:
{
"code": "BAD_EVENT_QUEUE_ID",
"msg": "Bad event queue id: 1518820930:1",
"queue_id": "1518820930:1",
"result": "error",
}
InvalidMessageError:
allOf:
- $ref: "#/components/schemas/JsonErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
example:
{
"msg": "Invalid message(s)",
"code": "BAD_REQUEST",
"result": "error",
}
NonExistingStreamError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
properties:
result: {}
msg: {}
code: {}
stream:
type: string
description: |
The name of the stream that could not be found.
example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream",
}
AddSubscriptionsResponse:
allOf:
- $ref: "#/components/schemas/JsonSuccessBase"
- additionalProperties: false
properties:
result: {}
msg: {}
subscribed:
type: object
description: |
A dictionary where the key is the email address of the user/bot and the
value is a list of the names of the streams that were subscribed to as a
result of the query.
additionalProperties:
description: |
`{email_address}`: List of the names of the streams that were subscribed
to as a result of the query.
type: array
items:
type: string
already_subscribed:
type: object
description: |
A dictionary where the key is the email address of the user/bot and the
value is a list of the names of the streams that the user/bot is already
subscribed to.
additionalProperties:
description: |
`{email_address}`: List of the names of the streams that the user is
already subscribed to.
type: array
items:
type: string
unauthorized:
type: array
items:
type: string
description: |
A list of names of streams that the requesting user/bot was not
authorized to subscribe to. Only present if `authorization_errors_fatal=false`.
InvalidApiKeyError:
allOf:
- $ref: "#/components/schemas/JsonError"
- example: {"msg": "Invalid API key", "result": "error"}
description: |
## Invalid API key
A typical failed JSON response for when the API key is invalid:
MissingArgumentError:
allOf:
- $ref: "#/components/schemas/CodedErrorBase"
- additionalProperties: false
description: |
## Missing request parameter(s)
A typical failed JSON response for when a required request parameter
is not supplied:
properties:
result: {}
msg: {}
code: {}
var_name:
type: string
description: |
It contains the information about the missing parameter.
example:
{
"code": "REQUEST_VARIABLE_MISSING",
"msg": "Missing 'content' argument",
"result": "error",
"var_name": "content",
}
UserNotAuthorizedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error",
}
description: |
## User not authorized for query
A typical failed JSON response for when the user is not authorized for
a query:
UserDeactivatedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "USER_DEACTIVATED",
"msg": "Account is deactivated",
"result": "error",
}
description: |
## User account deactivated
**Changes**: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's account is deactivated:
RateLimitedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "RATE_LIMIT_HIT",
"msg": "API usage exceeded rate limit",
"result": "error",
"retry-after": 28.706807374954224,
}
description: |
## Rate limit exceeded
The `retry-after` parameter in the response indicates how many seconds
the client must wait before making additional requests.
**Changes**: The `code` field was not present in rate
limit errors before Zulip 4.0 (feature level 36).
A typical failed JSON response for when a rate limit is exceeded:
RealmDeactivatedError:
allOf:
- $ref: "#/components/schemas/CodedError"
- example:
{
"code": "REALM_DEACTIVATED",
"msg": "This organization is deactivated",
"result": "error",
}
description: |
## Realm deactivated
**Changes**: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's organization is deactivated:
###################
# Shared responses
###################
responses:
SimpleSuccess:
description: Success.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/JsonSuccess"
- $ref: "#/components/schemas/SuccessDescription"
####################
# Shared parameters
####################
parameters:
Event_types:
name: event_types
in: query
description: |
A JSON-encoded array indicating which types of events you're interested
in. Values that you might find useful include:
- **message** (messages)
- **subscription** (changes in your subscriptions)
- **realm_user** (changes to users in the organization and
their properties, such as their name).
If you do not specify this parameter, you will receive all
events, and have to filter out the events not relevant to
your client in your client code. For most applications, one
is only interested in messages, so one specifies:
`event_types=['message']`
Event types not supported by the server are ignored, in order to simplify
the implementation of client apps that support multiple server versions.
content:
application/json:
schema:
type: array
items:
type: string
example: ["message"]
required: false
Narrow:
name: narrow
in: query
description: |
A JSON-encoded array of arrays of length 2 indicating the
narrow for which you'd like to receive events for. For
instance, to receive events for the stream `Denmark`, you
would specify `narrow=[['stream', 'Denmark']]`. Another
example is `narrow=[['is', 'private']]` for private messages.
Default is `[]`.
content:
application/json:
schema:
type: array
items:
type: array
items:
type: string
default: []
example: [["stream", "Denmark"]]
required: false
AllPublicStreams:
name: all_public_streams
in: query
description: |
Whether you would like to request message events from all public
streams. Useful for workflow bots that you'd like to see all new messages
sent to public streams. (You can also subscribe the user to private streams).
schema:
type: boolean
default: false
example: true
UserGroupId:
name: user_group_id
in: path
description: |
The ID of the target user group.
schema:
type: integer
example: 22
required: true
QueueId:
name: queue_id
in: query
description: |
The ID of an event queue that was previously registered via
`POST /api/v1/register` (see [Register a queue](/api/register-queue)).
schema:
type: string
example: 1375801870:2942
required: true
StreamIdInPath:
name: stream_id
in: path
description: |
The ID of the stream to access.
schema:
type: integer
example: 1
required: true
ClientGravatar:
name: client_gravatar
in: query
description: |
Whether the client supports computing gravatars URLs. If
enabled, `avatar_url` will be included in the response only
if there is a Zulip avatar, and will be `null` for users who
are using gravatar as their avatar. This option
significantly reduces the compressed size of user data,
since gravatar URLs are long, random strings and thus do not
compress well. The `client_gravatar` field is set to `true` if
clients can compute their own gravatars.
**Changes**: The default value of this parameter was `false`
prior to Zulip 5.0 (feature level 92).
schema:
type: boolean
default: true
example: false
RequiredContent:
name: content
in: query
description: |
The content of the message. Maximum message size of 10000 bytes.
schema:
type: string
example: Hello
required: true
OptionalContent:
name: content
in: query
description: |
The content of the message. Maximum message size of 10000 bytes.
schema:
type: string
example: Hello
MessageId:
name: message_id
in: path
description: |
The target message's ID.
schema:
type: integer
example: 43
required: true
UserId:
name: user_id
in: path
description: |
The target user's ID.
schema:
type: integer
example: 12
required: true
MutedUserId:
name: muted_user_id
in: path
description: |
The ID of the user to mute/un-mute.
schema:
type: integer
example: 10
required: true
StreamPostPolicy:
name: stream_post_policy
in: query
description: |
[Policy][permission-level] for which users can post messages to the stream.
- 1 => Any user can post.
- 2 => Only administrators can post.
- 3 => Only [full members][calc-full-member] can post.
- 4 => Only moderators can post.
**Changes**: New in Zulip 3.0, replacing the previous
`is_announcement_only` boolean.
[permission-level]: /api/roles-and-permissions#permission-levels
[calc-full-member]: /api/roles-and-permissions#determining-if-a-user-is-a-full-member
schema:
type: integer
default: 1
example: 2
required: false
HistoryPublicToSubscribers:
name: history_public_to_subscribers
in: query
description: |
Whether the stream's message history should be available to
newly subscribed members, or users can only access messages
they actually received while subscribed to the stream.
Corresponds to the [shared history](/help/stream-permissions)
option in documentation.
schema:
type: boolean
example: false
required: false
IncludeSubscribers:
name: include_subscribers
in: query
description: |
Whether each returned stream object should include a `subscribers`
field containing a list of the user IDs of its subscribers.
(This may be significantly slower in organizations with
thousands of users subscribed to many streams.)
**Changes**: New in Zulip 2.1.0.
schema:
type: boolean
default: false
example: true
IncludeCustomProfileFields:
name: include_custom_profile_fields
in: query
description: |
Whether the client wants [custom profile field](/help/add-custom-profile-fields)
data to be included in the response.
**Changes**: New in Zulip 2.1.0. Previous versions do no offer these
data via the API.
schema:
type: boolean
default: false
example: true
Principals:
name: principals
in: query
description: |
A list of user ids (preferred) or Zulip display email
addresses of the users to be subscribed to or unsubscribed
from the streams specified in the `subscriptions` parameter. If
not provided, then the requesting user/bot is subscribed.
**Changes**: The integer format is new in Zulip 3.0 (feature level 9).
content:
application/json:
schema:
oneOf:
- type: array
items:
type: string
- type: array
items:
type: integer
example: ["ZOE@zulip.com"]
ReactionType:
name: reaction_type
in: query
description: |
A string indicating the type of emoji. Each emoji `reaction_type`
has an independent namespace for values of `emoji_code`.
If an API client is adding/removing a vote on an existing reaction,
it should pass this parameter using the value the server provided
for the existing reaction for specificity. Supported values:
- `unicode_emoji` : In this namespace, `emoji_code` will be a
dash-separated hex encoding of the sequence of Unicode codepoints
that define this emoji in the Unicode specification.
- `realm_emoji` : In this namespace, `emoji_code` will be the ID of
the uploaded [custom emoji](/help/custom-emoji).
- `zulip_extra_emoji` : These are special emoji included with Zulip.
In this namespace, `emoji_code` will be the name of the emoji (e.g.
"zulip").
**Changes**: In Zulip 3.0 (feature level 2), this become
optional for [custom emoji](/help/custom-emoji);
previously, this endpoint assumed `unicode_emoji` if this
parameter was not specified.
schema:
type: string
example: "unicode_emoji"
required: false
EmojiCode:
name: emoji_code
in: query
description: |
A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
For most API clients, you won't need this, but it's important
for Zulip apps to handle rare corner cases when
adding/removing votes on an emoji reaction added previously by
another user.
If the existing reaction was added when the Zulip server was
using a previous version of the emoji data mapping between
Unicode codepoints and human-readable names, sending the
`emoji_code` in the data for the original reaction allows the
Zulip server to correctly interpret your upvote as an upvote
rather than a reaction with a "different" emoji.
schema:
type: string
example: "1f419"
required: false
MessageRetentionDays:
name: message_retention_days
in: query
description: |
Number of days that messages sent to this stream will be stored
before being automatically deleted by the [message retention
policy](/help/message-retention-policy). Two special string format
values are supported:
- "realm_default" => Return to the organization-level setting.
- "unlimited" => Retain messages forever.
**Changes**: Prior to Zulip 5.0 (feature level 91), retaining
messages forever was encoded using `"forever"` instead of
`"unlimited"`.
New in Zulip 3.0 (feature level 17).
schema:
oneOf:
- type: string
- type: integer
example: "20"
required: false
LinkifierPattern:
name: pattern
in: query
description: |
The [Python regular
expression](https://docs.python.org/3/howto/regex.html) that should
trigger the linkifier.
schema:
type: string
example: "#(?P<id>[0-9]+)"
required: true
LinkifierURLFormatString:
name: url_format_string
in: query
description: |
The URL used for the link. If you used named groups for the `pattern`,
you can insert their content here with
`%(name_of_the_capturing_group)s`.
schema:
type: string
example: https://github.com/zulip/zulip/issues/%(id)s
required: true
DirectMemberOnly:
name: direct_member_only
in: query
description: |
Whether to consider only the direct members of user group and not members
of its subgroups. Default is `False`.
schema:
type: boolean
example: false
required: false
Reference in New Issue View Git Blame Copy Permalink