mirror of https://github.com/zulip/zulip.git
11204 lines
508 KiB
YAML
11204 lines
508 KiB
YAML
# 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
|
|
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 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:
|
|
$ref: "#/components/schemas/ApiKeyResponse"
|
|
/dev_fetch_api_key:
|
|
post:
|
|
operationId: dev_fetch_api_key
|
|
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:
|
|
$ref: "#/components/schemas/ApiKeyResponse"
|
|
/events:
|
|
get:
|
|
operationId: get_events
|
|
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).
|
|
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/master/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"
|
|
- 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/add-an-alert-word) 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 a user's clients when that user's display settings
|
|
have changed.
|
|
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-notification-settings) have changed.
|
|
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 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 timezone 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 timezone 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 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 of the user in integer.
|
|
enum:
|
|
- 100
|
|
- 200
|
|
- 400
|
|
- 600
|
|
- 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.
|
|
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/Messages"
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
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_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.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"op": "update",
|
|
"type": "stream",
|
|
"property": "invite_only",
|
|
"value": true,
|
|
"history_public_to_subscribers": true,
|
|
"stream_id": 11,
|
|
"name": "test_stream",
|
|
"id": 0,
|
|
}
|
|
- 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:
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
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.
|
|
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,
|
|
}
|
|
- 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:
|
|
emoji_code: {}
|
|
emoji_name: {}
|
|
reaction_type: {}
|
|
user_id: {}
|
|
user: {}
|
|
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.
|
|
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 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".
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
The text content of the status message.
|
|
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",
|
|
"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.
|
|
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
|
|
recipient_id:
|
|
type: integer
|
|
description: |
|
|
Only present for private messages.
|
|
|
|
The ID of the user (or group of users) who received the private message.
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
Only present for private messages.
|
|
|
|
The ID of the user who sent the private message.
|
|
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",
|
|
"recipient_id": 10,
|
|
"sender_id": 8,
|
|
"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
|
|
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
|
|
webapp 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 has been edited.
|
|
Sent to all users who had received the original
|
|
message.
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/EventIdSchema"
|
|
type:
|
|
allOf:
|
|
- $ref: "#/components/schemas/EventTypeSchema"
|
|
- enum:
|
|
- update_message
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user who sent the message.
|
|
message_id:
|
|
type: integer
|
|
description: |
|
|
The ID of the message which was edited.
|
|
edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The timestamp when the message was edited.
|
|
stream_name:
|
|
type: string
|
|
description: |
|
|
Only present if the message was originally sent to a stream.
|
|
|
|
The name of the stream that the message was sent to.
|
|
stream_id:
|
|
type: integer
|
|
description: |
|
|
Only present if the message was originally sent to a stream.
|
|
|
|
The ID of the stream that the message was sent to.
|
|
new_stream_id:
|
|
type: integer
|
|
description: |
|
|
Note: Only present if message(s) were moved to a different stream.
|
|
|
|
The ID of the stream that the message was moved to.
|
|
orig_content:
|
|
type: string
|
|
description: |
|
|
The original Markdown content of the message, before this edit.
|
|
orig_rendered_content:
|
|
type: string
|
|
description: |
|
|
The original content of the message, before this edit, rendered as HTML.
|
|
prev_rendered_content_version:
|
|
type: integer
|
|
description: |
|
|
The Markdown processor version number for the pre-edit message.
|
|
content:
|
|
type: string
|
|
description: |
|
|
The new content of the message, in the original markdown.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
The new content of the message, rendered in HTML.
|
|
is_me_message:
|
|
type: boolean
|
|
description: |
|
|
Whether the message is now a [/me status message][status-messages].
|
|
propagate_mode:
|
|
type: string
|
|
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.
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
orig_subject:
|
|
type: string
|
|
description: |
|
|
The original topic of the message. Only present if the topic of the message
|
|
was changed.
|
|
subject:
|
|
type: string
|
|
description: |
|
|
The current topic of the message following the edit.
|
|
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 filter](/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.
|
|
message_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
For edits changing the stream or topic of multiple messages,
|
|
the list of IDs of other messages to be moved as well.
|
|
|
|
The messages are guaranteed to have all been previously in the
|
|
sam stream and topic.
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's personal [message flags][message-flags] for the message
|
|
following the edit. The client should compare these to the original
|
|
flags to identify cases where a mention was added by the edit.
|
|
items:
|
|
type: string
|
|
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": [],
|
|
"id": 0,
|
|
}
|
|
- type: object
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent when a user starts typing a private or group private message. Sent
|
|
to all clients for users who would receive the message being typed.
|
|
|
|
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
|
|
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: |
|
|
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.
|
|
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 private or group private message. Sent
|
|
to all clients for users who would receive the message that was
|
|
previously being typed.
|
|
|
|
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
|
|
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: |
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
example:
|
|
{
|
|
"type": "update_message_flags",
|
|
"op": "remove",
|
|
"operation": "remove",
|
|
"flag": "starred",
|
|
"messages": [63],
|
|
"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,
|
|
},
|
|
"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 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.
|
|
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
|
|
a [custom emoji](/help/add-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/allow-anyone-to-join-without-an-invitation)
|
|
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/allow-anyone-to-join-without-an-invitation)
|
|
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/allow-anyone-to-join-without-an-invitation)
|
|
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: |
|
|
Event sent to all users in a Zulip organization when the
|
|
configuration of the organization (realm) has changed.
|
|
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
|
|
additionalProperties: false
|
|
description: |
|
|
Event sent to all users in a Zulip organization when the
|
|
configuration of the organization (realm) has changed.
|
|
|
|
Unlike realm / update, 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
|
|
description: |
|
|
Always `"default"`. Present for backwards-compatibility with older
|
|
clients that predate the `update_dict` event style.
|
|
data:
|
|
type: object
|
|
description: |
|
|
An object containing the properties that have changed.
|
|
properties:
|
|
add_emoji_by_admins_only:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization is configured to only allow administrators
|
|
to upload new custom emoji.
|
|
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_deleting:
|
|
type: boolean
|
|
description: |
|
|
Whether messages can be deleted in this Zulip organization.
|
|
bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
The policy for which users can create bot users in this organization.
|
|
create_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The policy for which users can create streams in this organization.
|
|
invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
The policy for which users can add other users to streams in this
|
|
organization.
|
|
wildcard_mention_policy:
|
|
type: integer
|
|
description: |
|
|
The policy 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 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.
|
|
|
|
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).
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
The default UI language for new users joining this organization.
|
|
default_twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Whether new members of this organization will see times displayed in
|
|
24-hour time (true) or 12-hour time (false).
|
|
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).
|
|
disallow_disposable_email_addresses:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization disallows disposable email
|
|
addresses.
|
|
email_address_visibility:
|
|
type: integer
|
|
description: |
|
|
The policy 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).
|
|
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.
|
|
invite_required:
|
|
type: boolean
|
|
description: |
|
|
Whether an invitation is required to join this organization.
|
|
invite_by_admins_only:
|
|
type: boolean
|
|
description: |
|
|
If true, only organization administrators can invite new users to join.
|
|
If false, any [Member](/help/roles-and-permissions) can invite new users
|
|
to join the organization. [Help center article](/help/invite-new-users#change-who-can-send-invitations).
|
|
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).
|
|
mandatory_topics:
|
|
type: boolean
|
|
description: |
|
|
Whether [topics are required](/help/require-topics) for messages in this organization.
|
|
message_retention_days:
|
|
type: integer
|
|
description: |
|
|
The default [message retention policy](/help/message-retention-policy)
|
|
for this organization. Pass `"forever"` to request that messages
|
|
by retained forever (the default).
|
|
realm_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 this type of account information
|
|
an external user database like LDAP.
|
|
avatar_changes_disabled:
|
|
type: boolean
|
|
description: |
|
|
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 this type of account information
|
|
an external user database like LDAP.
|
|
emails_restricted_to_domains:
|
|
type: boolean
|
|
description: |
|
|
Whether [new users joining](/help/allow-anyone-to-join-without-an-invitation)
|
|
this organization are required to have an email
|
|
address in one of the `realm_domains` configured for the organization.
|
|
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.
|
|
? 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.
|
|
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](/help/restrict-permissions-of-new-members)
|
|
for the purpose of settings that restrict access to new members.
|
|
digest_weekday:
|
|
type: integer
|
|
description: |
|
|
The day of the week when the organization will send
|
|
its weekly digest email to inactive users.
|
|
private_message_policy:
|
|
type: integer
|
|
description: |
|
|
Policy for [who can send private messages](/help/restrict-private-messages)
|
|
in this organization.
|
|
|
|
* 1 = Everyone
|
|
* 2 = Nobody
|
|
user_group_edit_policy:
|
|
type: integer
|
|
description: |
|
|
The organization's policy for [who can manage user groups
|
|
](/help/restrict-user-group-management).
|
|
|
|
* 1 = All members can create and edit user groups
|
|
* 2 = Only organization administrators can create and edit user groups
|
|
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.
|
|
message_content_delete_limit_seconds:
|
|
type: integer
|
|
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).
|
|
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.
|
|
allow_message_editing:
|
|
type: boolean
|
|
description: |
|
|
Whether this organizations [message edit policy](/help/configure-message-editing-and-deletion)
|
|
allows editing the content of messages.
|
|
allow_community_topic_editing:
|
|
type: boolean
|
|
description: |
|
|
Whether [community topic editing](/help/community-topic-edits) is enabled
|
|
in this organization.
|
|
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).
|
|
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).
|
|
icon_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's [profile icon](/help/create-your-organization-profile).
|
|
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_file_size:
|
|
type: integer
|
|
description: |
|
|
The maximum file size allowed for the organization's
|
|
icon. Useful for UI allowing editing the organization's icon.
|
|
logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's wide logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
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.
|
|
night_logo_url:
|
|
type: string
|
|
description: |
|
|
The URL of the organization's night theme wide-format logo configured in the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
night_logo_source:
|
|
type: string
|
|
description: |
|
|
String indicating whether the organization's night 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:
|
|
type: integer
|
|
description: |
|
|
The maximum file size allowed for the uploaded organization logos.
|
|
bot_domain:
|
|
type: string
|
|
description: |
|
|
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: |
|
|
The URL for the organization.
|
|
available_video_chat_providers:
|
|
type: object
|
|
description: |
|
|
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 chat provider.
|
|
additionalProperties:
|
|
description: |
|
|
`{provider_name}`: Dictionary containing the details of the
|
|
video chat 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 chat provider.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the video chat provider.
|
|
presence_disabled:
|
|
type: boolean
|
|
description: |
|
|
Whether online presence of other users is shown in this
|
|
organization.
|
|
settings_send_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
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.
|
|
is_zephyr_mirror_realm:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization is a Zephyr mirror realm.
|
|
email_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
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.
|
|
password_auth_enabled:
|
|
type: boolean
|
|
description: |
|
|
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).
|
|
push_notifications_enabled:
|
|
type: boolean
|
|
description: |
|
|
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).
|
|
upload_quota:
|
|
type: integer
|
|
nullable: true
|
|
description: |
|
|
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.
|
|
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)
|
|
zulip_plan_is_not_limited:
|
|
type: boolean
|
|
description: |
|
|
Whether the organization is using a limited (Zulip Cloud Free) plan.
|
|
upgrade_text_for_wide_organization_logo:
|
|
type: string
|
|
description: |
|
|
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.
|
|
default_external_accounts:
|
|
type: object
|
|
description: |
|
|
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: |
|
|
The base URL the organization uses to create Jitsi video calls.
|
|
development_environment:
|
|
type: boolean
|
|
description: |
|
|
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: |
|
|
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: |
|
|
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: |
|
|
This Zulip server's configured minimum `zxcvbn` minimum guesses.
|
|
Necessary for password change UI to show whether the password
|
|
will be accepted.
|
|
max_file_upload_size_mib:
|
|
type: integer
|
|
description: |
|
|
The maximum file size that can be uploaded to this Zulip server.
|
|
max_avatar_file_size_mib:
|
|
type: integer
|
|
description: |
|
|
The maximum avatar size that can be uploaded to this Zulip server.
|
|
server_inline_image_preview:
|
|
type: boolean
|
|
description: |
|
|
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: |
|
|
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: |
|
|
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: |
|
|
Whether the server allows name changes. Similar to
|
|
`realm_name_changes_disabled` but based on the `NAME_CHANGES_DISABLED`
|
|
Zulip server level setting.
|
|
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.
|
|
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.
|
|
additionalProperties: false
|
|
example:
|
|
{
|
|
"type": "realm",
|
|
"op": "update_dict",
|
|
"property": "default",
|
|
"data":
|
|
{
|
|
"allow_message_editing": false,
|
|
"message_content_edit_limit_seconds": 0,
|
|
"allow_community_topic_editing": false,
|
|
},
|
|
"id": 0,
|
|
}
|
|
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:
|
|
$ref: "#/components/schemas/BadEventQueueIdError"
|
|
delete:
|
|
operationId: delete_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:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/BadEventQueueIdError"
|
|
/get_stream_id:
|
|
get:
|
|
operationId: 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"
|
|
- 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",
|
|
}
|
|
/mark_all_as_read:
|
|
post:
|
|
operationId: mark_all_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:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
/mark_stream_as_read:
|
|
post:
|
|
operationId: mark_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: 42
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
/mark_topic_as_read:
|
|
post:
|
|
operationId: mark_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: 42
|
|
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:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
/attachments:
|
|
get:
|
|
operationId: 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"
|
|
- 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,
|
|
}
|
|
/messages:
|
|
get:
|
|
operationId: 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.
|
|
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: 42
|
|
- 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
|
|
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:
|
|
$ref: "#/components/schemas/GetMessages"
|
|
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
|
|
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"
|
|
- $ref: "#/components/parameters/Topic"
|
|
- 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"
|
|
- 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:
|
|
- $ref: "#/components/schemas/NonExistingStreamError"
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid email 'eeshan@zulip.com'",
|
|
"result": "error",
|
|
}
|
|
/messages/{message_id}/history:
|
|
get:
|
|
operationId: get_message_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"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
message_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
topic:
|
|
type: string
|
|
description: |
|
|
the topic for the message.
|
|
prev_topic:
|
|
type: string
|
|
description: |
|
|
the topic for the message before being edited.
|
|
content:
|
|
type: string
|
|
description: |
|
|
the body of the message.
|
|
rendered_content:
|
|
type: string
|
|
description: |
|
|
the already rendered, HTML version of `content`.
|
|
prev_content:
|
|
type: string
|
|
description: |
|
|
the body of the message before being edited.
|
|
prev_rendered_content:
|
|
type: string
|
|
description: |
|
|
the already rendered, HTML version of
|
|
`prev_content`.
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
the ID of the user that made the edit.
|
|
content_html_diff:
|
|
type: string
|
|
description: |
|
|
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 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:
|
|
$ref: "#/components/schemas/InvalidMessageError"
|
|
/messages/flags:
|
|
post:
|
|
operationId: update_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).
|
|
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"
|
|
- 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
|
|
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"
|
|
- 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
|
|
tags: ["messages"]
|
|
description: |
|
|
Add an [emoji reaction](/help/emoji-reactions) to a message.
|
|
|
|
`POST {{ api_url }}/v1/messages/{message_id}/reactions`
|
|
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",
|
|
}
|
|
|
|
delete:
|
|
operationId: remove_reaction
|
|
tags: ["messages"]
|
|
description: |
|
|
Remove an [emoji reaction](/help/emoji-reactions) from a message.
|
|
|
|
`DELETE {{ api_url }}/v1/messages/{message_id}/reactions`
|
|
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",
|
|
}
|
|
/messages/matches_narrow:
|
|
get:
|
|
operationId: check_messages_match_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/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_raw_message
|
|
tags: ["messages"]
|
|
description: |
|
|
Get the raw content of a message.
|
|
|
|
`GET {{ api_url }}/v1/messages/{msg_id}`
|
|
|
|
This is a rarely-used endpoint relevant for clients that primarily
|
|
work with HTML-rendered messages but might need to occasionally fetch
|
|
the message's raw Markdown (e.g. for pre-filling a message-editing
|
|
UI).
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
raw_content:
|
|
type: string
|
|
description: |
|
|
The raw content of the message.
|
|
example:
|
|
{
|
|
"raw_content": "**Don't** forget your towel!",
|
|
"result": "success",
|
|
"msg": "",
|
|
}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/InvalidMessageError"
|
|
patch:
|
|
operationId: update_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.
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
- $ref: "#/components/parameters/Topic"
|
|
- name: propagate_mode
|
|
in: query
|
|
description: |
|
|
Which message(s) should be edited: just the one indicated in
|
|
`message_id`, messages in the same topic that had been sent after this
|
|
one, or all of them.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
default: change_one
|
|
example: change_all
|
|
- name: 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 ID of the stream to access.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
"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",
|
|
}
|
|
delete:
|
|
operationId: delete_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.
|
|
parameters:
|
|
- $ref: "#/components/parameters/MessageId"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/InvalidMessageError"
|
|
- allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to delete this message",
|
|
"result": "error",
|
|
}
|
|
/user_uploads:
|
|
post:
|
|
operationId: upload_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
|
|
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"
|
|
- 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
|
|
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"
|
|
- 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
|
|
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).
|
|
parameters:
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
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,
|
|
"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,
|
|
"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,
|
|
"user_id": 23,
|
|
"bot_type": 1,
|
|
"timezone": "",
|
|
"is_bot": true,
|
|
},
|
|
],
|
|
}
|
|
post:
|
|
operationId: create_user
|
|
tags: ["users"]
|
|
description: |
|
|
{!can-create-users-only.md!}
|
|
|
|
Create a new user account via the API.
|
|
|
|
`POST {{ api_url }}/v1/users`
|
|
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"
|
|
- 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",
|
|
}
|
|
|
|
/users/{user_id}/reactivate:
|
|
post:
|
|
operationId: reactivate_user
|
|
tags: ["users"]
|
|
description: |
|
|
{!api-admin-only.md!}
|
|
|
|
[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/JsonSuccess"
|
|
- example: {"msg": "", "result": "success"}
|
|
|
|
/users/{user_id_or_email}/presence:
|
|
get:
|
|
operationId: 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"
|
|
- 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
|
|
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"
|
|
- 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_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,
|
|
"is_guest": false,
|
|
"is_bot": false,
|
|
"is_active": true,
|
|
"timezone": "",
|
|
"date_joined": "2019-10-20T07:50:53.728864+00:00",
|
|
"max_message_id": 30,
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_id": 5,
|
|
"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
|
|
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"
|
|
- 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",
|
|
}
|
|
/users/me/{stream_id}/topics:
|
|
get:
|
|
operationId: get_stream_topics
|
|
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"
|
|
- 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",
|
|
}
|
|
/users/me/subscriptions:
|
|
get:
|
|
operationId: get_subscriptions
|
|
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.
|
|
parameters:
|
|
- $ref: "#/components/parameters/IncludeSubscribers"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
# 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
|
|
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.
|
|
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
|
|
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 craeted
|
|
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
|
|
- $ref: "#/components/parameters/HistoryPublicToSubscribers"
|
|
- $ref: "#/components/parameters/StreamPostPolicy"
|
|
- $ref: "#/components/parameters/MessageRetentionDays"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- example:
|
|
{
|
|
"already_subscribed": {},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {"iago@zulip.com": ["new stream"]},
|
|
}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- example:
|
|
{
|
|
"already_subscribed":
|
|
{"newbie@zulip.com": ["new stream"]},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {},
|
|
}
|
|
"400":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- example:
|
|
{
|
|
"msg": "Unable to access stream (private_stream).",
|
|
"result": "error",
|
|
}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/AddSubscriptionsResponse"
|
|
- example:
|
|
{
|
|
"already_subscribed": {},
|
|
"msg": "",
|
|
"result": "success",
|
|
"subscribed": {},
|
|
"unauthorized": ["private_stream"],
|
|
}
|
|
patch:
|
|
operationId: update_subscriptions
|
|
tags: ["streams"]
|
|
description: |
|
|
Update which streams you are 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"
|
|
- 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
|
|
tags: ["streams"]
|
|
description: |
|
|
Unsubscribe yourself or other users from one or more streams.
|
|
|
|
`DELETE {{ api_url }}/v1/users/me/subscriptions`
|
|
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"
|
|
- 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:
|
|
$ref: "#/components/schemas/NonExistingStreamError"
|
|
/users/me/subscriptions/muted_topics:
|
|
patch:
|
|
operationId: mute_topic
|
|
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`
|
|
|
|
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: 42
|
|
required: false
|
|
- name: topic
|
|
in: query
|
|
description: |
|
|
The topic to (un)mute. Note that the request will succeed regardless of
|
|
whether any messages have been sent to the specified topic.
|
|
schema:
|
|
type: string
|
|
example: dinner
|
|
required: true
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether to mute (`add`) or unmute (`remove`) the provided topic.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- add
|
|
- remove
|
|
example: add
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{"msg": "Topic already muted", "result": "error"}
|
|
- allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{"msg": "Topic is not muted", "result": "error"}
|
|
/users/{user_id}/subscriptions/{stream_id}:
|
|
get:
|
|
operationId: 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"
|
|
- additionalProperties: false
|
|
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
|
|
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}`
|
|
parameters:
|
|
- name: emoji_name
|
|
required: true
|
|
in: path
|
|
description: |
|
|
The name that should be associated with the uploaded emoji image/gif.
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
filename:
|
|
type: string
|
|
format: binary
|
|
example: /path/to/img.png
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
|
|
/realm/emoji:
|
|
get:
|
|
operationId: get_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"
|
|
- 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
|
|
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"
|
|
- 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
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
{!api-admin-only.md!}
|
|
|
|
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).
|
|
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:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
post:
|
|
operationId: create_custom_profile_field
|
|
tags: ["server_and_organizations"]
|
|
description: |
|
|
{!api-admin-only.md!}
|
|
|
|
[Create a custom profile field](/help/add-custom-profile-fields) in the user's organization.
|
|
|
|
`POST {{ api_url }}/v1/realm/profile_fields`
|
|
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"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID for the custom profile field.
|
|
example: {"result": "success", "msg": "", "id": 9}
|
|
/users/me/subscriptions/properties:
|
|
post:
|
|
operationId: 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`
|
|
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`.
|
|
|
|
The possible values for each `property` and `value` pairs are:
|
|
|
|
* `color` (string): the hex value of the user's display color for the stream.
|
|
* `is_muted` (boolean): whether the stream is
|
|
[muted](/help/mute-a-stream). 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 value.
|
|
* `pin_to_top` (boolean): whether to pin the stream at the top of the stream list.
|
|
* `desktop_notifications` (boolean): whether to show desktop notifications
|
|
for all messages sent to the stream.
|
|
* `audible_notifications` (boolean): whether to play a sound
|
|
notification for all messages sent to the stream.
|
|
* `push_notifications` (boolean): whether to trigger a mobile push
|
|
notification for all messages sent to the stream.
|
|
* `email_notifications` (boolean): whether to trigger an email
|
|
notification for all messages sent to the stream.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
[
|
|
{"stream_id": 1, "property": "pin_to_top", "value": true},
|
|
{"stream_id": 3, "property": "color", "value": "#f00f00"},
|
|
]
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
subscription_data:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
properties:
|
|
property:
|
|
type: string
|
|
description: |
|
|
The property to be changed. It is one of:
|
|
|
|
* `color`: The hex value of the user's personal display color for the stream.<br>
|
|
* `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 value.<br>
|
|
* `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.<br>
|
|
* `audible_notifications`: Whether to play a sound notification for all
|
|
messages sent to the stream.<br>
|
|
* `push_notifications`: Whether to trigger a mobile push notification for
|
|
all messages sent to the stream.<br>
|
|
* `email_notifications`: Whether to trigger an email notification for all
|
|
messages sent to the stream.<br>
|
|
* `in_home_view`: Whether to mute the stream (legacy property)<br>
|
|
* `wildcard_mentions_notify`: whether wildcard mentions trigger notifications
|
|
as though they were personal mentions in this stream.<br>
|
|
A null value means the value of this setting
|
|
should be inherited from the user-level default
|
|
setting, wildcard_mentions_notify, for
|
|
this stream.
|
|
|
|
enum:
|
|
- color
|
|
- push_notifications
|
|
- is_muted
|
|
- pin_to_top
|
|
- desktop_notifications
|
|
- audible_notifications
|
|
- push_notifications
|
|
- email_notifications
|
|
- in_home_view
|
|
- wildcard_mentions_notify
|
|
value:
|
|
description: |
|
|
The desired value of the property
|
|
oneOf:
|
|
- type: boolean
|
|
- type: string
|
|
stream_id:
|
|
description: |
|
|
The desired value of the property
|
|
type: integer
|
|
description: |
|
|
The same `subscription_data` array sent by the client for the request.
|
|
example:
|
|
{
|
|
"subscription_data":
|
|
[
|
|
{
|
|
"property": "pin_to_top",
|
|
"value": true,
|
|
"stream_id": 1,
|
|
},
|
|
{
|
|
"property": "color",
|
|
"value": "#f00f00",
|
|
"stream_id": 3,
|
|
},
|
|
],
|
|
"result": "success",
|
|
"msg": "",
|
|
}
|
|
/users/{email}:
|
|
get:
|
|
operationId: get_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).*
|
|
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"
|
|
- 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,
|
|
"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
|
|
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).*
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserId"
|
|
- $ref: "#/components/parameters/ClientGravatar"
|
|
- $ref: "#/components/parameters/IncludeCustomProfileFields"
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
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,
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"is_active": true,
|
|
"email": "hamlet@zulip.com",
|
|
},
|
|
}
|
|
patch:
|
|
operationId: update_user
|
|
tags: ["users"]
|
|
description: |
|
|
{!api-admin-only.md!}
|
|
|
|
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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
example: NewName
|
|
required: false
|
|
- name: role
|
|
in: query
|
|
description: |
|
|
New [role](/help/roles-and-permissions) for the user. Roles are encoded as:
|
|
|
|
* Organization owner: 100
|
|
* Organization administrator: 200
|
|
* 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.
|
|
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",
|
|
}
|
|
|
|
delete:
|
|
operationId: deactivate_user
|
|
tags: ["users"]
|
|
description: |
|
|
{!api-admin-only.md!}
|
|
|
|
[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"
|
|
- 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",
|
|
}
|
|
/realm/filters:
|
|
get:
|
|
operationId: 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/filters`
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
filters:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
description: |
|
|
An array of tuples, each representing one of
|
|
the linkifiers set up in the
|
|
organization. Each of these tuples contain the
|
|
pattern, the formatted URL and the filter's
|
|
ID, in that order. See the [Create
|
|
linkifiers](/api/add-linkifier) article for
|
|
details on what each field means.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"filters":
|
|
[
|
|
[
|
|
"#(?P<id>[0-9]+)",
|
|
"https://github.com/zulip/zulip/issues/%(id)s",
|
|
1,
|
|
],
|
|
],
|
|
"result": "success",
|
|
}
|
|
post:
|
|
operationId: add_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:
|
|
- 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
|
|
- 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
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- 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
|
|
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 filter that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
/register:
|
|
post:
|
|
operationId: register_queue
|
|
tags: ["real_time_events"]
|
|
description: |
|
|
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.
|
|
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). 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. 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.
|
|
New in Zulip 3.0 (feature level 18).
|
|
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`.
|
|
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"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
queue_id:
|
|
type: string
|
|
description: |
|
|
The ID of the queue that has been allocated for your client.
|
|
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.
|
|
alert_words:
|
|
type: array
|
|
description: |
|
|
Present if `alert_words` is present in `fetch_event_types`.
|
|
|
|
An array of strings, each an [alert word](/help/add-an-alert-word)
|
|
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.
|
|
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`.
|
|
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
|
|
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"
|
|
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_filters:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
description: |
|
|
Present if `realm_filters` is present in `fetch_event_types`.
|
|
|
|
An array of tuples (fixed-length arrays) where each tuple describes
|
|
a single realm filter ([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.
|
|
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: {}
|
|
history_public_to_subscribers: {}
|
|
first_message_id: {}
|
|
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 messags 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.
|
|
additionalProperties: false
|
|
properties:
|
|
sender_id:
|
|
type: integer
|
|
description: |
|
|
The user id of the other participant in a PM conversation.
|
|
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.
|
|
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:
|
|
sender_ids:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: |
|
|
Array containing the id of the users who have sent recent messages
|
|
on this stream under the given topic which have been unread by the user.
|
|
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 huddle(group PMs)
|
|
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.
|
|
stream_name_max_length:
|
|
type: integer
|
|
description: |
|
|
Present if `stream` 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.
|
|
stream_description_max_length:
|
|
type: integer
|
|
description: |
|
|
Present if `stream` 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.
|
|
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.
|
|
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: |
|
|
Whether the user has marked themself "away".
|
|
status_text:
|
|
type: string
|
|
description: |
|
|
The text content of the status message.
|
|
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.
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_login_emails:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_stream_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
wildcard_mentions_notify:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
notification_sound:
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
pm_content_in_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
desktop_icon_count_display:
|
|
type: integer
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
realm_name_in_notifications:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
presence_enabled:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
The current value of this global notification setting for the user.
|
|
See [update-notification-settings](/api/update-notification-settings)
|
|
for details on notification settings.
|
|
available_notification_sounds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
Present if `update_global_notifications` is present in `fetch_event_types`.
|
|
|
|
Array containing the names of the notification sound options supported by
|
|
this Zulip server. Only relevant to support UI for configuring notification
|
|
sounds.
|
|
color_scheme:
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
The color scheme selected by the user.
|
|
default_language:
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
The default language chosen by the user.
|
|
demote_inactive_streams:
|
|
type: integer
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen to demote inactive streams.
|
|
dense_mode:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has switched on dense mode. Dense mode is an experimental
|
|
feature that is only available in development environments.
|
|
emojiset:
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
The name of the emojiset that the user has chosen.
|
|
fluid_layout_width:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen for the layout width to be fluid.
|
|
default_view:
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
The [default view](/help/change-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`.
|
|
high_contrast_mode:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether has switched on high contrast mode.
|
|
left_side_userlist:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen for the userlist to be displayed
|
|
on the left side of the screen (for desktop app and webapp) in narrow
|
|
windows.
|
|
starred_message_counts:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen the number of starred messages to
|
|
be displayed similar to unread counts.
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
The timezone configured for the user. This is used primarily to display
|
|
the user's timezone to other users.
|
|
translate_emoticons:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen for emoticons to be translated into emoji
|
|
in the Zulip compose box.
|
|
twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Whether the user has chosen a twenty four hour time display (true)
|
|
or a twelve hour one (false).
|
|
emojiset_choices:
|
|
description: |
|
|
Present if `update_display_settings` is present in `fetch_event_types`.
|
|
|
|
Array of dictionaries where each dictionary describes an emojiset
|
|
supported by this version of the Zulip server.
|
|
|
|
Only relevant to clients with configuration UI for choosing an emojiset;
|
|
the currently selected emojiset is available in the `emojiset` key.
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: |
|
|
Object describing a emojiset.
|
|
additionalProperties: false
|
|
properties:
|
|
key:
|
|
type: string
|
|
description: |
|
|
The key or the name of the emojiset which will be the value
|
|
of `emojiset` if this emojiset is chosen.
|
|
text:
|
|
type: string
|
|
description: |
|
|
The text describing the emojiset.
|
|
realm_add_emoji_by_admins_only:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether the organization is configured to only allow administrators
|
|
to upload new custom emoji.
|
|
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_allow_message_deleting:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether messages can be deleted in this Zulip organization.
|
|
realm_bot_creation_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The policy for which users can create bot users in this organization.
|
|
realm_create_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The policy for which users can create streams in this organization.
|
|
realm_invite_to_stream_policy:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The policy 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 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 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.
|
|
|
|
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).
|
|
realm_default_language:
|
|
type: string
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The default UI language for new users joining this organization.
|
|
realm_default_twenty_four_hour_time:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether new members of this organization will see times displayed in
|
|
24-hour time (true) or 12-hour time (false).
|
|
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 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).
|
|
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_by_admins_only:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
If true, only organization administrators can invite new users to join.
|
|
If false, any [Member](/help/roles-and-permissions) can invite new users
|
|
to join the organization. [Help center article](/help/invite-new-users#change-who-can-send-invitations).
|
|
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. Pass `"forever"` to request that messages
|
|
by retained forever (the default).
|
|
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 this type of account information
|
|
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 this type of account information
|
|
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/allow-anyone-to-join-without-an-invitation)
|
|
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_video_chat_provider:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The configured video call provider for the organization.
|
|
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](/help/restrict-permissions-of-new-members)
|
|
for the purpose of settings that restrict access to new members.
|
|
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 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 for [who can manage user groups
|
|
](/help/restrict-user-group-management).
|
|
|
|
* 1 = All members can create and edit user groups
|
|
* 2 = Only organization administrators can create and edit user groups
|
|
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
|
|
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).
|
|
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_allow_community_topic_editing:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
Whether [community topic editing](/help/community-topic-edits) is enabled
|
|
in this organization.
|
|
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:
|
|
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.
|
|
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 night 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 night 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:
|
|
type: integer
|
|
description: |
|
|
Present if `realm` is present in `fetch_event_types`.
|
|
|
|
The maximum file size allowed for the uploaded organization logos.
|
|
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 chat provider.
|
|
additionalProperties:
|
|
description: |
|
|
`{provider_name}`: Dictionary containing the details of the
|
|
video chat 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 chat provider.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the video chat 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:
|
|
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.
|
|
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.
|
|
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.
|
|
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_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
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is allowed to create streams with
|
|
the organization's [stream creation policy](/help/configure-who-can-create-streams).
|
|
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).
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is an [organization administrator](/help/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](/help/roles-and-permissions).
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the current user is a [guest user](/help/roles-and-permissions).
|
|
enter_sends:
|
|
type: boolean
|
|
description: |
|
|
Present if `realm_user` is present in `fetch_event_types`.
|
|
|
|
Whether the user setting for [sending on pressing Enter](/help/enable-enter-to-send)
|
|
in the compose box is enabled.
|
|
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:
|
|
email: {}
|
|
is_bot: {}
|
|
avatar_url: {}
|
|
avatar_version: {}
|
|
full_name: {}
|
|
is_admin: {}
|
|
is_owner: {}
|
|
bot_type: {}
|
|
user_id: {}
|
|
bot_owner_id: {}
|
|
is_active: {}
|
|
is_guest: {}
|
|
timezone: {}
|
|
date_joined: {}
|
|
delivery_email: {}
|
|
profile_data: {}
|
|
is_cross_realm_bot:
|
|
type: boolean
|
|
description: |
|
|
Whether the user is a cross realm bot.
|
|
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",
|
|
},
|
|
},
|
|
"result": "success",
|
|
"zulip_feature_level": 2,
|
|
"zulip_version": "2.1.0",
|
|
}
|
|
/server_settings:
|
|
get:
|
|
operationId: get_server_settings
|
|
tags: ["server_and_organizations"]
|
|
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
|
|
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
|
|
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_version:
|
|
type: string
|
|
description: |
|
|
The version of Zulip running in the server.
|
|
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.
|
|
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.
|
|
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).
|
|
example:
|
|
{
|
|
"authentication_methods":
|
|
{
|
|
"password": true,
|
|
"dev": true,
|
|
"email": true,
|
|
"ldap": false,
|
|
"remoteuser": false,
|
|
"github": true,
|
|
"azuread": false,
|
|
"google": true,
|
|
"saml": true,
|
|
},
|
|
"zulip_version": "2.0.6+git",
|
|
"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>",
|
|
"result": "success",
|
|
"external_authentication_methods":
|
|
[
|
|
{
|
|
"name": "saml:idp_name",
|
|
"display_name": "SAML",
|
|
"display_icon": null,
|
|
"login_url": "/accounts/login/social/saml/idp_name",
|
|
"signup_url": "/accounts/register/social/saml/idp_name",
|
|
},
|
|
{
|
|
"name": "google",
|
|
"display_name": "Google",
|
|
"display_icon": "/static/images/landing-page/logos/googl_e-icon.png",
|
|
"login_url": "/accounts/login/social/google",
|
|
"signup_url": "/accounts/register/social/google",
|
|
},
|
|
{
|
|
"name": "github",
|
|
"display_name": "GitHub",
|
|
"display_icon": "/static/images/landing-page/logos/github-icon.png",
|
|
"login_url": "/accounts/login/social/github",
|
|
"signup_url": "/accounts/register/social/github",
|
|
},
|
|
],
|
|
}
|
|
/settings/notifications:
|
|
patch:
|
|
operationId: update_notification_settings
|
|
tags: ["users"]
|
|
description: |
|
|
This endpoint is used to edit the user's global notification settings.
|
|
See [this endpoint](/api/update-subscription-settings) for
|
|
per-stream notification settings.
|
|
|
|
`PATCH {{ api_url }}/v1/settings/notifications`
|
|
parameters:
|
|
- name: enable_stream_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Enable visual desktop notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_stream_audible_notifications
|
|
in: query
|
|
description: |
|
|
Enable audible desktop notifications for stream messages.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: notification_sound
|
|
in: query
|
|
description: |
|
|
Notification sound name.
|
|
content:
|
|
application/json:
|
|
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: enable_offline_email_notifications
|
|
in: query
|
|
description: |
|
|
Enable email notifications for private messages and @-mentions received
|
|
when the user is offline.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_offline_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is offline.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_online_push_notifications
|
|
in: query
|
|
description: |
|
|
Enable mobile notification for private messages and @-mentions received
|
|
when the user is online.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_digest_emails
|
|
in: query
|
|
description: |
|
|
Enable digest emails when the user is away.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: enable_login_emails
|
|
in: query
|
|
description: |
|
|
Enable email notifications for new logins to account.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: message_content_in_email_notifications
|
|
in: query
|
|
description: |
|
|
Include the message's content in missed messages email notifications.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: pm_content_in_desktop_notifications
|
|
in: query
|
|
description: |
|
|
Include content of private messages in desktop notifications.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: wildcard_mentions_notify
|
|
in: query
|
|
description: |
|
|
Whether wildcard mentions (E.g. @**all**) should send notifications
|
|
like a personal mention.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: desktop_icon_count_display
|
|
in: query
|
|
description: |
|
|
Unread count summary (appears in desktop sidebar and browser tab)
|
|
|
|
* 1 - All unreads
|
|
* 2 - Private messages and mentions
|
|
* 3 - None
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 1
|
|
- 2
|
|
- 3
|
|
example: 1
|
|
- name: realm_name_in_notifications
|
|
in: query
|
|
description: |
|
|
Include organization name in subject of missed message emails.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: presence_enabled
|
|
in: query
|
|
description: |
|
|
Display the presence status to other users when online.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
enable_desktop_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_desktop_notifications`, if it was changed in
|
|
this request.
|
|
enable_digest_emails:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_digest_emails`, if it was changed in this
|
|
request.
|
|
enable_offline_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_offline_email_notifications`, if it was changed
|
|
in this request.
|
|
enable_offline_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_offline_push_notifications`, if it was changed
|
|
in this request.
|
|
enable_online_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_online_push_notifications`, if it was changed in
|
|
this request.
|
|
enable_sounds:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_sounds`, if it was changed in this request.
|
|
enable_stream_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_stream_email_notifications`, if it was changed
|
|
in this request.
|
|
enable_stream_push_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_stream_push_notifications`, if it was changed in
|
|
this request.
|
|
enable_stream_audible_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `enable_stream_audible_notifications`, if it was changed
|
|
in this request.
|
|
message_content_in_email_notifications:
|
|
type: boolean
|
|
description: |
|
|
The setting for `message_content_in_email_notifications`, if it was
|
|
changed in this request.
|
|
example:
|
|
{
|
|
"enable_offline_push_notifications": true,
|
|
"enable_online_push_notifications": true,
|
|
"msg": "",
|
|
"result": "success",
|
|
}
|
|
/streams:
|
|
get:
|
|
operationId: get_streams
|
|
tags: ["streams"]
|
|
description: |
|
|
Get all streams that the user has access to.
|
|
|
|
`GET {{ api_url }}/v1/streams`
|
|
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"
|
|
- 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: {}
|
|
history_public_to_subscribers: {}
|
|
first_message_id: {}
|
|
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",
|
|
}
|
|
/streams/{stream_id}:
|
|
delete:
|
|
operationId: archive_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"
|
|
- example: {"msg": "", "result": "success"}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream id",
|
|
"result": "error",
|
|
}
|
|
patch:
|
|
operationId: update_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}`
|
|
parameters:
|
|
- $ref: "#/components/parameters/StreamIdInPath"
|
|
- name: description
|
|
in: query
|
|
description: |
|
|
The new description for the stream.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
example: This stream is related to football dicsussions.
|
|
required: false
|
|
- name: new_name
|
|
in: query
|
|
description: |
|
|
The new name for the stream.
|
|
content:
|
|
application/json:
|
|
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
|
|
- $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"
|
|
- example: {"msg": "", "result": "success"}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream id",
|
|
"result": "error",
|
|
}
|
|
/typing:
|
|
post:
|
|
operationId: 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 private message or group private 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.
|
|
|
|
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.
|
|
parameters:
|
|
- name: op
|
|
in: query
|
|
description: |
|
|
Whether the user has started (`start`) or stopped (`stop`) to type.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- start
|
|
- stop
|
|
example: start
|
|
required: true
|
|
- name: to
|
|
in: query
|
|
description: |
|
|
The user_ids of the recipients of the message being typed. Typing
|
|
notifications are only supported for private messages. Send a
|
|
JSON-encoded list of user_ids. (Use a list even if there is only one
|
|
recipient.)
|
|
|
|
**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
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
|
|
/user_groups/create:
|
|
post:
|
|
operationId: create_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"
|
|
- example: {"msg": "", "result": "success"}
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"result": "error",
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user ID: 500",
|
|
}
|
|
/user_groups/{user_group_id}/members:
|
|
post:
|
|
operationId: 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`
|
|
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"
|
|
/user_groups/{user_group_id}:
|
|
patch:
|
|
operationId: update_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",
|
|
}
|
|
delete:
|
|
operationId: remove_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"
|
|
- example: {"result": "success", "msg": ""}
|
|
|
|
"400":
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonError"
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid user group",
|
|
"result": "error",
|
|
}
|
|
|
|
/user_groups:
|
|
get:
|
|
operationId: get_user_groups
|
|
tags: ["users"]
|
|
description: |
|
|
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"
|
|
- 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
|
|
name:
|
|
type: string
|
|
description: |
|
|
User group name.
|
|
description: |
|
|
A list of `user_group` objects, which contain a `description`, a `name`,
|
|
their `id` and the list of members of the user group.
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"user_groups":
|
|
[
|
|
{
|
|
"description": "Characters of Hamlet",
|
|
"id": 1,
|
|
"name": "hamletcharacters",
|
|
"members": [3, 4],
|
|
},
|
|
{
|
|
"description": "Other users",
|
|
"id": 2,
|
|
"name": "other users",
|
|
"members": [1, 2],
|
|
},
|
|
],
|
|
}
|
|
/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
|
|
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"
|
|
"403":
|
|
description: |
|
|
Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/UserDeactivatedError"
|
|
- $ref: "#/components/schemas/RealmDeactivatedError"
|
|
/zulip-outgoing-webhook:
|
|
post:
|
|
operationId: zulip_outgoing_webhooks
|
|
tags: ["webhooks"]
|
|
description: |
|
|
Outgoing webhooks allows 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
|
|
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 dict 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: {}
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
topic_links: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
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
|
|
description: |
|
|
Create a video call URL for a Big Blue Button video call.
|
|
Requires Big Blue Button to be configured on the Zulip server.
|
|
responses:
|
|
"200":
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/components/schemas/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
url:
|
|
description: |
|
|
The URL for the Big Blue Button video call.
|
|
type: string
|
|
example: "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22"
|
|
example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"url": "/calls/bbb/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:
|
|
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: {}
|
|
history_public_to_subscribers: {}
|
|
first_message_id: {}
|
|
is_announcement_only: {}
|
|
BasicStreamBase:
|
|
type: object
|
|
description: |
|
|
Object containing basic details about the stream.
|
|
additionalProperties: false
|
|
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 for which users can post messages to the stream.
|
|
|
|
* 1 => Any user can post.
|
|
* 2 => Only administrators can post.
|
|
* 3 => Only full members can post.
|
|
* 4 => Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0, replacing the previous
|
|
`is_announcement_only` boolean.
|
|
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: {}
|
|
default_events_register_stream: {}
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id: {}
|
|
services: {}
|
|
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: {}
|
|
default_events_register_stream: {}
|
|
default_all_public_streams: {}
|
|
avatar_url: {}
|
|
owner_id: {}
|
|
services: {}
|
|
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.
|
|
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.
|
|
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.
|
|
id:
|
|
type: integer
|
|
description: |
|
|
The ID of the user group.
|
|
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 short description of a stream in text/markdown format,
|
|
intended to be used to prepopulate UI for editing a stream's
|
|
description.
|
|
rendered_description:
|
|
type: string
|
|
description: |
|
|
A short description of a 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.
|
|
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 for which users can post messages to the stream.
|
|
|
|
* 1 => Any user can post.
|
|
* 2 => Only administrators can post.
|
|
* 3 => Only full members can post.
|
|
* 4 => Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0, replacing the previous
|
|
`is_announcement_only` boolean.
|
|
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: {}
|
|
EmojiReactionBase:
|
|
type: object
|
|
properties:
|
|
emoji_code:
|
|
type: string
|
|
description: |
|
|
A unique identifier, defining the specific emoji codepoint requested,
|
|
within the namespace of the `reaction_type`.
|
|
|
|
For example, for `unicode_emoji`, this will be an encoding of the
|
|
Unicode codepoint.
|
|
emoji_name:
|
|
type: string
|
|
description: |
|
|
Name of the emoji.
|
|
reaction_type:
|
|
type: string
|
|
description: |
|
|
One of the following values:
|
|
|
|
* `unicode_emoji`: Unicode emoji (`emoji_code` will be its Unicode
|
|
codepoint).
|
|
* `realm_emoji`: [Custom emoji](/help/add-custom-emoji).
|
|
(`emoji_code` will be its ID).
|
|
* `zulip_extra_emoji`: Special emoji included with Zulip. Exists to
|
|
namespace the `zulip` emoji.
|
|
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: |
|
|
Dictionary with data on the user who added the reaction, including
|
|
the user ID as the `id` field. **Note**: In the [events
|
|
API](/api/get-events), this `user` dictionary
|
|
confusing had the user ID in a field called `user_id`
|
|
instead. We recommend ignoring fields other than the user
|
|
ID. **Deprecated** and to be removed in a future release
|
|
once core clients have migrated to use the `user_id` field.
|
|
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.
|
|
Messages:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url: {}
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
topic_links: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
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.
|
|
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]
|
|
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.
|
|
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][linkification-filters] 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.
|
|
|
|
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.
|
|
type:
|
|
type: string
|
|
description: |
|
|
The type of the message: `stream` or `private`.
|
|
GetMessages:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MessagesBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
avatar_url: {}
|
|
client: {}
|
|
content: {}
|
|
content_type: {}
|
|
display_recipient: {}
|
|
id: {}
|
|
is_me_message: {}
|
|
reactions: {}
|
|
recipient_id: {}
|
|
sender_email: {}
|
|
sender_full_name: {}
|
|
sender_id: {}
|
|
sender_realm_str: {}
|
|
stream_id: {}
|
|
subject: {}
|
|
topic_links: {}
|
|
submessages: {}
|
|
timestamp: {}
|
|
type: {}
|
|
flags:
|
|
type: array
|
|
description: |
|
|
The user's [message flags][message-flags] for the message.
|
|
items:
|
|
type: string
|
|
last_edit_timestamp:
|
|
type: integer
|
|
description: |
|
|
The UNIX timestamp for when the message was last edited,
|
|
in UTC seconds.
|
|
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.
|
|
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.
|
|
User:
|
|
allOf:
|
|
- $ref: "#/components/schemas/UserBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
email: {}
|
|
is_bot: {}
|
|
avatar_url: {}
|
|
avatar_version: {}
|
|
full_name: {}
|
|
is_admin: {}
|
|
is_owner: {}
|
|
bot_type: {}
|
|
user_id: {}
|
|
bot_owner_id: {}
|
|
is_active: {}
|
|
is_guest: {}
|
|
timezone: {}
|
|
date_joined: {}
|
|
delivery_email: {}
|
|
profile_data: {}
|
|
UserBase:
|
|
type: object
|
|
description: |
|
|
A dictionary containing basic data on a given Zulip user.
|
|
properties:
|
|
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.
|
|
is_bot:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a bot or full account.
|
|
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}`.
|
|
full_name:
|
|
type: string
|
|
description: |
|
|
Full name of the user or bot, used for all display purposes.
|
|
is_admin:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is an organization administrator.
|
|
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).
|
|
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.
|
|
user_id:
|
|
type: integer
|
|
description: |
|
|
The unique ID of the user.
|
|
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.
|
|
is_active:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user account has been deactivated.
|
|
is_guest:
|
|
type: boolean
|
|
description: |
|
|
A boolean specifying whether the user is a guest user.
|
|
timezone:
|
|
type: string
|
|
description: |
|
|
The time zone of the user.
|
|
date_joined:
|
|
type: string
|
|
description: |
|
|
The time the user account was created.
|
|
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"
|
|
profile_data:
|
|
type: object
|
|
description: |
|
|
A dictionary containing custom profile field data for the user. Each entry
|
|
maps the integer ID of a custom profile field in the organization to a
|
|
dictionary containing the user's data for that field. Generally the data
|
|
includes just a single `value` key; for those custom profile fields
|
|
supporting Markdown, a `rendered_value` key will also be present.
|
|
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
|
|
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/JsonSuccessBase"
|
|
- additionalProperties: false
|
|
properties:
|
|
result: {}
|
|
msg: {}
|
|
raw_content:
|
|
type: string
|
|
description: |
|
|
The raw content of the message.
|
|
example:
|
|
{
|
|
"msg": "Invalid message(s)",
|
|
"code": "BAD_REQUEST",
|
|
"result": "error",
|
|
}
|
|
NonExistingStreamError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/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"}
|
|
MissingArgumentError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedErrorBase"
|
|
- additionalProperties: false
|
|
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",
|
|
}
|
|
UserDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "USER_DEACTIVATED",
|
|
"msg": "Account is deactivated",
|
|
"result": "error",
|
|
}
|
|
RealmDeactivatedError:
|
|
allOf:
|
|
- $ref: "#/components/schemas/CodedError"
|
|
- example:
|
|
{
|
|
"code": "REALM_DEACTIVATED",
|
|
"msg": "This organization is deactivated",
|
|
"result": "error",
|
|
}
|
|
|
|
###################
|
|
# Shared responses
|
|
###################
|
|
responses:
|
|
SimpleSuccess:
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JsonSuccess"
|
|
|
|
####################
|
|
# 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']`
|
|
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: 1
|
|
required: true
|
|
Topic:
|
|
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
|
|
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.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
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: 42
|
|
required: true
|
|
UserId:
|
|
name: user_id
|
|
in: path
|
|
description: |
|
|
The target user's ID.
|
|
schema:
|
|
type: integer
|
|
example: 12
|
|
required: true
|
|
StreamPostPolicy:
|
|
name: stream_post_policy
|
|
in: query
|
|
description: |
|
|
Policy for which users can post messages to the stream.
|
|
|
|
* 1 => Any user can post.
|
|
* 2 => Only administrators can post.
|
|
* 3 => Only full members can post.
|
|
* 4 => Only moderators can post.
|
|
|
|
**Changes**: New in Zulip 3.0, replacing the previous
|
|
`is_announcement_only` boolean.
|
|
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:
|
|
type: array
|
|
items:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: ["ZOE@zulip.com"]
|
|
ReactionType:
|
|
name: reaction_type
|
|
in: query
|
|
description: |
|
|
If an app 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`: Unicode emoji (`emoji_code` will be its Unicode codepoint).
|
|
* `realm_emoji`: Custom emoji. (`emoji_code` will be its ID).
|
|
* `zulip_extra_emoji`: Special emoji included with Zulip. Exists to
|
|
namespace the `zulip` emoji.
|
|
|
|
**Changes**: In Zulip 3.0 (feature level 2), this become
|
|
optional for [custom emoji](/help/add-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 "diffenent" 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.
|
|
* "forever" => Retain messages forever.
|
|
|
|
**Changes**: New in Zulip 3.0 (feature level 17).
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
- type: integer
|
|
example: "20"
|
|
required: false
|