# This file contains the API definitions for the Zulip REST API.
#
# For details on the OpenAPI specification, see http://swagger.io/specification
#
# Our own documentation lives at
#
# https://zulip.readthedocs.io/en/latest/subsystems/openapi-api-docs.html
#
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST API
description: Powerful open source group chat
contact:
url: https://zulipchat.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: 'https://your.zulip.server/api/v1'
#######################
# Endpoint definitions
#######################
paths:
/events:
get:
description: Receive new events from
[a registered event queue](/api/register-queue).
parameters:
- name: queue_id
in: query
description: The ID of a queue that you registered via
`POST /api/v1/register`
(see [Register a queue](/api/register-queue)).
schema:
type: string
example: 1375801870:2942
- 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
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
events:
type: array
description: An array of `event` objects (possibly
zero-length if `dont_block` is set) of events with
IDs newer than `last_event_id`. Event IDs are
guaranted to be increasing, but they are not
guaranteed to be consecutive.
- example:
{
"events": [
{
"id": 0,
"message": {
"avatar_url": "https://url/for/othello-bots/avatar",
"client": "website",
"content": "Something is rotten in the state of Denmark.",
"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",
"sender_short_name": "othello-bot",
"subject": "Castle",
"subject_links": [],
"timestamp": 1375978403,
"type": "stream"
},
"type": "message"
},
{
"id": 1,
"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": [
{
"email": "hamlet@example.com",
"full_name": "Hamlet of Denmark",
"id": 31572,
"short_name": "hamlet"
}
],
"id": 12345679,
"recipient_id": 18391,
"sender_email": "othello-bot@example.com",
"sender_full_name": "Othello Bot",
"sender_id": 13215,
"sender_realm_str": "example",
"sender_short_name": "othello-bot",
"subject": "",
"subject_links": [],
"timestamp": 1375978404,
"type": "private"
},
"type": "message"
}
],
"msg": "",
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/BadEventQueueIdError'
delete:
description: Delete a previously registered queue.
parameters:
- name: queue_id
in: query
description: The ID of a queue that you registered via
`POST /api/v1/register`(see [Register a queue](/api/register-queue).
schema:
type: string
example: 1375801870:2942
required: true
security:
- basicAuth: []
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:
description: Get the unique ID of a given stream.
parameters:
- name: stream
in: query
description: The name of the stream to retrieve the ID for.
schema:
type: string
example: Denmark
required: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
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"
}
/messages:
post:
description: Send a message.
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: The destination stream, or a CSV/JSON-encoded list
containing the usernames (emails) of the recipients.
schema:
type: string
example: aaron@zulip.com, iago@zulip.com
required: true
- name: subject
in: query
description: The topic of the message. Only required if `type` is
`stream`, ignored otherwise. Maximum length of 60 characters.
schema:
type: string
default:
example: Castle
- name: content
in: query
description: The content of the message. Maximum message size of
10000 bytes.
schema:
type: string
example: Hello
required: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
id:
type: integer
description: The ID assigned to the message sent.
- example:
{
"msg": "",
"id": 42,
"result": "success"
}
'400_non_existing_stream':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/NonExistingStreamError'
'400_non_existing_user':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error"
}
/messages/{message_id}:
patch:
description: Edit a message that has already been sent.
parameters:
- name: message_id
in: path
description: The ID of the message that you wish to edit/update.
schema:
type: integer
example: 42
required: true
- name: subject
in: query
description: The topic of the message. Only required for stream
messages. Maximum length of 60 characters.
schema:
type: string
default:
example: Castle
- name: propagate_mode
in: query
description: "Which message(s) should be edited: just the one
indicated in `message_id`, messages in the same topic that had been
sent after this one, or all of them."
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
- name: content
in: query
description: The content of the message. Maximum message size of 10000
bytes.
schema:
type: string
example: Hello
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- 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"
}
/messages/render:
post:
description: Render a message to HTML.
parameters:
- name: content
in: query
description: The content of the message.
schema:
type: string
example: '**foo**'
required: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
rendered:
type: string
description: The rendered HTML.
- example:
{
"msg": "",
"rendered": "foo
",
"result": "success"
}
/user_uploads:
post:
description: Upload a single file and get the corresponding URI.
requestBody:
content:
multipart/form-data:
schema:
properties:
filename:
type: string
format: binary
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
uri:
type: string
description: The URI of the uploaded file.
- example:
{
"msg": "",
"result": "success",
"uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt"
}
/users:
get:
description: Retrieve all users in a realm.
parameters:
- name: client_gravatar
in: query
description: The `client_gravatar` field is set to `true` if clients
can compute their own gravatars.
schema:
type: boolean
default: false
example: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
members:
type: array
description: A list of `member` objects, each containing
details of a user in the realm (like their email, name,
avatar, user type...).
- example:
{
"members": [
{
"avatar_url": "https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1",
"bot_type": null,
"email": "AARON@zulip.com",
"full_name": "aaron",
"is_active": true,
"is_admin": false,
"is_bot": false,
"user_id": 1
},
{
"avatar_url": "https://secure.gravatar.com/avatar/77c3871a68c8d70356156029fd0a4999?d=identicon&version=1",
"bot_type": null,
"email": "cordelia@zulip.com",
"full_name": "Cordelia Lear",
"is_active": true,
"is_admin": false,
"is_bot": false,
"user_id": 3
},
{
"avatar_url": "https://secure.gravatar.com/avatar/0cbf08f3a355995fa2ec542246e35123?d=identicon&version=1",
"bot_type": null,
"email": "newbie@zulip.com",
"full_name": "New User",
"is_active": true,
"is_admin": false,
"is_bot": false,
"user_id": 24
}
],
"msg": "",
"result": "success"
}
post:
description: Create a new user in a realm.
parameters:
- name: email
in: query
description: The email address of the new user.
schema:
type: string
example: newbie@zulip.com
required: true
- name: password
in: query
description: The password of the new user.
schema:
type: string
example: abdec@7982
required: true
- name: full_name
in: query
description: The full name of the new user.
schema:
type: string
example: John Smith
required: true
- name: short_name
in: query
description: The short name of the new user.
schema:
type: string
example: jsmith
required: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
'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/me/{stream_id}/topics:
get:
description: Get all the topics in a specific stream.
parameters:
- name: stream_id
in: path
description: The unique ID of the stream.
schema:
type: integer
example: 42
required: true
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
topics:
type: array
items:
type: object
properties:
max_id:
description:
The ID of the last message sent to the topic.
type: number
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:
post:
description: Subscribe one or more users to one or more streams.
parameters:
- name: subscriptions
in: query
description: "A list of dictionaries, where each dictionary contains
key/value pairs specifying a particular stream to subscribe to.
**Note**: This argument is called `streams` and not `subscriptions`
in our Python API."
schema:
type: array
items:
type: object
example: [{"name": "Verona"}]
required: true
- name: invite_only
in: query
description: A boolean specifying whether the streams specified in
`subscriptions` are invite-only or not.
schema:
type: boolean
default: false
example: true
- name: announce
in: query
description: If `announce` is `True` and one of the streams specified
in `subscriptions` has to be created (i.e. doesn't exist to begin
with), an announcement will be made notifying that a new stream was
created.
schema:
type: boolean
example: true
- name: principals
in: query
description: A list of email addresses of the users that will be
subscribed to the streams specified in the `subscriptions` argument.
If not provided, then the requesting user/bot is subscribed.
schema:
type: array
items:
type: string
default: []
example: ['ZOE@zulip.com']
- 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
returned JSON payload indicates that there was an authorization
error, but the response is still considered a successful one.
schema:
type: boolean
default: true
example: false
security:
- basicAuth: []
responses:
'200_without_principals':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {
"iago@zulip.com": [
"new stream"
]
}
}
'200_already_subscribed':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {
"newbie@zulip.com": [
"new stream"
]
},
"msg": "",
"result": "success",
"subscribed": {}
}
'400_unauthorized_errors_fatal_true':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error"
}
'400_unauthorized_errors_fatal_false':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": [
"private_stream"
]
}
delete:
description: Unsubscribe yourself or other users from one or more
streams.
parameters:
- name: subscriptions
in: query
description: A list of stream names to unsubscribe from. This argument
is called `streams` in our Python API.
schema:
type: array
items:
type: string
example: ['Verona', 'Denmark']
required: true
- name: principals
in: query
description: A list of email addresses of the users that will be
unsubscribed from the streams specified in the `subscriptions`
argument. If not provided, then the requesting user/bot is
unsubscribed.
schema:
type: array
items:
type: string
default:
example: ['ZOE@zulip.com']
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
not_subscribed:
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_subscribed": [],
"removed": [
"new stream"
],
"result": "success"
}
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/NonExistingStreamError'
/register:
post:
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 (by default, the API returns the raw text
that the user entered)
schema:
type: boolean
default: false
example: true
- name: client_gravatar
in: query
description: The `client_gravatar` field is set to `true` if clients
can compute their own gravatars.
schema:
type: boolean
default: false
example: true
- 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 in the list of users in your realm)
If you do not specify this argument, 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']`"
schema:
type: string
example: event_types=['message']
- name: all_public_streams
in: query
description: Set to `True` if you would like to receive events that
occur within all public streams.
schema:
type: boolean
default: false
example: true
- name: include_subscribers
in: query
description: Set to `True` if you would like to receive events that
include the subscribers for each stream.
schema:
type: boolean
default: false
example: true
- name: fetch_event_types
in: query
description: Same as the `event_types` argument 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 argument defaults to `None`.
schema:
type: string
example: event_types=['message']
- name: narrow
in: query
description: A JSON-encoded array 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.
schema:
type: string
default: narrow=[]
example: narrow=['stream', 'Denmark']
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
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`.
- example:
{
"last_event_id": -1,
"msg": "",
"queue_id": "1517975029:0",
"realm_emoji": {
"1": {
"author": {
"email": "iago@zulip.com",
"full_name": "Iago",
"id": 5
},
"deactivated": false,
"id": "1",
"name": "green_tick",
"source_url": "/user_avatars/1/emoji/images/1.png"
}
},
"result": "success"
}
/streams:
get:
description: Get all streams that the user has access to.
parameters:
- name: include_public
in: query
description: Include all public streams.
schema:
type: boolean
default: true
example: false
- 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
security:
- basicAuth: []
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
streams:
type: array
items:
type: object
description: A list of `stream` objects, which contain a
`description`, a `name`, their `stream_id` and whether
they are `invite_only` or not.
- 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"
}
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:
JsonResponse:
type: object
properties:
result:
type: string
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
- example:
{
"msg": "",
"result": "success"
}
JsonError:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- error
msg:
type: string
CodedError:
allOf:
- $ref: '#/components/schemas/JsonError'
- properties:
code:
type: string
description: A string that identifies the error.
BadEventQueueIdError:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
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"
}
NonExistingStreamError:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
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/JsonSuccess'
- properties:
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.
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.
unauthorized:
type: array
items:
type: string
description: A list of names of streams that the requesting
user/bot was not authorized to subscribe to.
###################
# Shared responses
###################
responses:
SimpleSuccess:
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'