mirror of https://github.com/zulip/zulip.git
2533 lines
88 KiB
YAML
2533 lines
88 KiB
YAML
# 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/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://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:
|
|
/dev_fetch_api_key:
|
|
post:
|
|
description: Gather a token bound to a user account, to identify and
|
|
authenticate them when making operations with the API. This token must
|
|
be used as the password in the rest of the endpoints that require
|
|
Basic authentication.
|
|
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
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ApiKeyResponse'
|
|
/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": "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",
|
|
"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": "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,
|
|
"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"
|
|
}
|
|
/mark_all_as_read:
|
|
post:
|
|
description: Mark all the user's unread messages as read. This is often
|
|
called "bankruptcy" in Zulip.
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
/mark_stream_as_read:
|
|
post:
|
|
description: Mark all the unread messages in a stream as read.
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: The ID of the stream whose messages should be marked as
|
|
read.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
/mark_topic_as_read:
|
|
post:
|
|
description: Mark all the unread messages in a topic as read.
|
|
parameters:
|
|
- name: stream_id
|
|
in: query
|
|
description: The ID of the stream that contains the topic.
|
|
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
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
/messages:
|
|
get:
|
|
description: Fetch messages that match a specific narrow.
|
|
parameters:
|
|
- name: anchor
|
|
in: query
|
|
description: The message ID to fetch messages near.
|
|
Required unless `use_first_unread_anchor` is set to true.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
- name: use_first_unread_anchor
|
|
in: query
|
|
description: Whether to use the (computed by the server) first unread message
|
|
matching the narrow as the `anchor`. Mutually exclusive with `anchor`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: num_before
|
|
in: query
|
|
description: The number of messages with IDs less than the anchor to retrieve.
|
|
schema:
|
|
type: integer
|
|
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
|
|
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).
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
default: []
|
|
example: [{"operator": "sender", "operand"}]
|
|
- 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.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- 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
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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
|
|
items:
|
|
type: object
|
|
- 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": [
|
|
{
|
|
"short_name": "hamlet",
|
|
"id": 4,
|
|
"is_mirror_dummy": false,
|
|
"email": "hamlet@zulip.com",
|
|
"full_name": "King Hamlet"
|
|
},
|
|
{
|
|
"short_name": "iago",
|
|
"id": 5,
|
|
"is_mirror_dummy": false,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago"
|
|
},
|
|
{
|
|
"short_name": "prospero",
|
|
"id": 8,
|
|
"is_mirror_dummy": false,
|
|
"email": "prospero@zulip.com",
|
|
"full_name": "Prospero from The Tempest"
|
|
}
|
|
],
|
|
"content_type": "text/html",
|
|
"is_me_message": false,
|
|
"sender_short_name": "hamlet",
|
|
"timestamp": 1527921326,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 27,
|
|
"subject_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,
|
|
"sender_short_name": "hamlet",
|
|
"timestamp": 1527939746,
|
|
"sender_id": 4,
|
|
"sender_full_name": "King Hamlet",
|
|
"recipient_id": 20,
|
|
"subject_links": [],
|
|
"client": "populate_db",
|
|
"avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1",
|
|
"submessages": [],
|
|
"sender_email": "hamlet@zulip.com",
|
|
"reactions": []
|
|
}
|
|
]
|
|
}
|
|
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: topic
|
|
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}:
|
|
get:
|
|
description: Get the raw content of a message.
|
|
parameters:
|
|
- name: message_id
|
|
in: path
|
|
description: The target message's ID.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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:
|
|
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"
|
|
}
|
|
delete:
|
|
description: Delete a message.
|
|
parameters:
|
|
- name: message_id
|
|
in: path
|
|
description: The ID of the message to delete.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
'400_invalid_message':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InvalidMessageError'
|
|
'400_not_admin':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/CodedError'
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to delete this message",
|
|
"result": "error"
|
|
}
|
|
/messages/{message_id}/history:
|
|
get:
|
|
description: Get the different versions of a previously edited message.
|
|
parameters:
|
|
- name: message_id
|
|
in: path
|
|
description: The ID of the message you want to fetch the history of.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
message_history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: A chronologically sorted array of
|
|
`snapshot` objects, each one with the values of the
|
|
message after the edition.
|
|
- 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:
|
|
description: Add or remove flags in a list of messages.
|
|
parameters:
|
|
- name: messages
|
|
in: query
|
|
description: An array containing the IDs of the target messages.
|
|
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
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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:
|
|
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": "<p><strong>foo</strong></p>",
|
|
"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,
|
|
"is_guest": false,
|
|
"user_id": 1,
|
|
"timezone" : "Africa/Bujumbura"
|
|
},
|
|
{
|
|
"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,
|
|
"is_guest": false,
|
|
"user_id": 3,
|
|
"timezone" : "Asia/Calcutta"
|
|
},
|
|
{
|
|
"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,
|
|
"is_guest": true,
|
|
"user_id": 24,
|
|
"timezone" : "Asia/Calcutta"
|
|
}
|
|
],
|
|
"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/{email}/presence:
|
|
get:
|
|
description: Get the presence status for a specific user.
|
|
parameters:
|
|
- name: email
|
|
in: path
|
|
description: The email address of the user whose presence you want to
|
|
fetch.
|
|
schema:
|
|
type: string
|
|
example: iago@zulip.com
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
presence:
|
|
type: object
|
|
description: An object containing the presence details
|
|
for every client the user has logged into.
|
|
- example:
|
|
{
|
|
"presence": {
|
|
"website": {
|
|
"timestamp": 1532697622,
|
|
"status": "active",
|
|
"pushable": false,
|
|
"client": "website"
|
|
},
|
|
"ZulipMobile": {
|
|
"timestamp": 1522687421,
|
|
"status": "active",
|
|
"pushable": false,
|
|
"client": "ZulipMobile"
|
|
},
|
|
"aggregated": {
|
|
"timestamp": 1532697622,
|
|
"status": "active",
|
|
"client": "website"
|
|
}
|
|
},
|
|
"result": "success",
|
|
"msg": ""
|
|
}
|
|
/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.
|
|
You can specify an initial description here when creating a new stream.
|
|
**Note**: This argument is called `streams` and not `subscriptions`
|
|
in our Python API."
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example: [{"name": "Verona", "description": "Italian City"}]
|
|
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'
|
|
/users/me/subscriptions/muted_topics:
|
|
patch:
|
|
description: Toggle muting for a specific topic the user is subscribed
|
|
to.
|
|
parameters:
|
|
- name: stream
|
|
in: query_function
|
|
description: The name of the stream in which to mute the topic.
|
|
schema:
|
|
type: string
|
|
example: Verona
|
|
required: true
|
|
- 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
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
'400_topic_already_muted':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonError'
|
|
- example:
|
|
{
|
|
"msg": "Topic already muted",
|
|
"result": "error"
|
|
}
|
|
'400_topic_not_muted':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonError'
|
|
- example:
|
|
{
|
|
"msg": "Topic is not muted",
|
|
"result": "error"
|
|
}
|
|
/realm/emoji/{emoji_name}:
|
|
post:
|
|
description: Upload a single emoji file.
|
|
parameters:
|
|
- name: emoji_name
|
|
in: path
|
|
description: The name that should be associated with the uploaded
|
|
emoji image/gif.
|
|
schema:
|
|
type: string
|
|
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'
|
|
|
|
/realm/emoji:
|
|
get:
|
|
description: Get all the custom emoji in the user's realm.
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
emoji:
|
|
type: object
|
|
description: An object that contains `emoji` objects,
|
|
each identified with their emoji ID as the key.
|
|
- 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,
|
|
"email": "iago@zulip.com",
|
|
"full_name": "Iago"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
/users/me/subscriptions/properties:
|
|
post:
|
|
description: Make bulk modifications of the subscription properties on
|
|
one or more streams the user is subscribed to.
|
|
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`.
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example: [{"stream_id": 1, "property": "pin_to_top", "value": true}]
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
subscription_data:
|
|
type: array
|
|
items:
|
|
type: object
|
|
description: The same `subscription_data` object sent
|
|
by the client for the request.
|
|
- example:
|
|
{
|
|
"subscription_data": [
|
|
{
|
|
"property": "pin_to_top",
|
|
"value": true,
|
|
"stream_id": 1
|
|
},
|
|
{
|
|
"property": "color",
|
|
"value": 'f00',
|
|
"stream_id": 3
|
|
}
|
|
],
|
|
"result": "success",
|
|
"msg": ""
|
|
}
|
|
/realm/filters:
|
|
get:
|
|
description: Fetch all the filters set up for the user's organization.
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
filters:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
type:
|
|
anyOf:
|
|
- string
|
|
- 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-linkifiers) 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:
|
|
description: Establish patterns in the messages that should be
|
|
automatically linkified.
|
|
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
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
id:
|
|
type: integer
|
|
description: The numeric ID assigned to this filter.
|
|
- example:
|
|
{
|
|
"id": 42,
|
|
"result": "success",
|
|
"msg": ""
|
|
}
|
|
/realm/filters/{filter_id}:
|
|
delete:
|
|
description: Remove an organization filter.
|
|
parameters:
|
|
- name: filter_id
|
|
in: path
|
|
description: The ID of the filter that you want to remove.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
/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 (otherwise the API will return 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:
|
|
<br/> <br/>
|
|
* **message** (messages), <br/>
|
|
* **subscription** (changes in your subscriptions), <br/>
|
|
* **realm_user** (changes in the list of users in your realm)
|
|
<br/> <br/>
|
|
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"
|
|
}
|
|
/server_settings:
|
|
get:
|
|
description: Fetch global settings for the Zulip server.
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
authentication_methods:
|
|
type: object
|
|
description: Each key-value pair in the object indicates
|
|
whether the authentication method is enabled on this
|
|
server.
|
|
zulip_version:
|
|
type: string
|
|
description: The version of Zulip running in the server.
|
|
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 usernames should have an email
|
|
address format. This is important if your server has
|
|
[LDAP authentication](https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory)
|
|
enabled with a username and password combination.
|
|
realm_uri:
|
|
type: string
|
|
description: The organization's URI.
|
|
realm_name:
|
|
type: string
|
|
description: The realm's name.
|
|
realm_icon:
|
|
type: string
|
|
description: The URI of the organization's mobile icon (usually
|
|
a square version of the logo).
|
|
realm_logo:
|
|
type: string
|
|
description: The URI of the organization's top-left navbar logo
|
|
(usually a wide rectangular version of the logo).
|
|
realm_night_logo:
|
|
type: string
|
|
description: The URI of the organization's top-left navbar logo in night_mode
|
|
(usually a wide rectangular version of the logo).
|
|
realm_description:
|
|
type: string
|
|
description: HTML description of the organization, as
|
|
configured by the
|
|
[organization profile](/help/create-your-organization-profile).
|
|
- example:
|
|
{
|
|
"realm_uri": "http://localhost:9991",
|
|
"push_notifications_enabled": false,
|
|
"msg": "",
|
|
"realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon",
|
|
"realm_logo": "/static/images/logo/zulip-org-logo.png",
|
|
"realm_night_logo": "static/images/logo/zulip-org-logo.png",
|
|
"realm_description": "<p>The Zulip development environment default organization. It's great for testing!</p>",
|
|
"email_auth_enabled": true,
|
|
"zulip_version": "1.9.0-rc1+git",
|
|
"realm_name": "Zulip Dev",
|
|
"authentication_methods": {
|
|
"github": true,
|
|
"ldap": false,
|
|
"password": true,
|
|
"remoteuser": false,
|
|
"email": true,
|
|
"google": true,
|
|
"dev": true
|
|
},
|
|
"result": "success",
|
|
"require_email_format_usernames": true
|
|
}
|
|
/settings/notifications:
|
|
patch:
|
|
description: Modify the user's preferences for 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: 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: message_content_in_email_notifications
|
|
in: query
|
|
description: Include the message's content in missed messages email
|
|
notifications.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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:
|
|
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
|
|
- 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
|
|
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"
|
|
}
|
|
/streams/{stream_id}:
|
|
delete:
|
|
description: Delete the stream with the given ID.
|
|
parameters:
|
|
- name: stream_id
|
|
in: path
|
|
description: The ID of the stream to be deleted.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
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:
|
|
description: Update the stream with the given ID.
|
|
parameters:
|
|
- name: stream_id
|
|
in: path
|
|
description: The ID of the stream to be updated.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
- name: description
|
|
in: query
|
|
description: The new description for the stream.
|
|
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.
|
|
schema:
|
|
type: string
|
|
example: "Italy"
|
|
required: false
|
|
- name: is_private
|
|
in: query
|
|
description: The new state of the stream.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
- name: is_announcement_only
|
|
in: query
|
|
description: The new state for the announcements.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
- name: history_public_to_subscribers
|
|
in: query
|
|
description: The new state for the history_public_to_subscribers.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
required: false
|
|
|
|
security:
|
|
- basicAuth: []
|
|
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:
|
|
description: Send an event indicating that the user has started or
|
|
stopped typing on their client.
|
|
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 recipients of the message being typed, in the same format used by the
|
|
send_message API. Typing notifications are only supported for private messages,
|
|
so this should be a JSON-encoded list of email addresses of the message's recipients.
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: ["iago@zulip.com", "polonius@zulip.com"]
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
|
|
/user_groups/create:
|
|
post:
|
|
description: Create a user group.
|
|
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.
|
|
schema:
|
|
type: array
|
|
example: [1, 2, 3, 4]
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
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/{group_id}:
|
|
patch:
|
|
description: Update the user group.
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: The ID of the group.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
- name: name
|
|
in: query
|
|
description: The new name of the group.
|
|
schema:
|
|
type: string
|
|
example: marketing
|
|
required: true
|
|
- name: description
|
|
in: query
|
|
description: The new description of the group.
|
|
schema:
|
|
type: string
|
|
example: The marketing team.
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
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"
|
|
}
|
|
delete:
|
|
description: Delete the user group.
|
|
parameters:
|
|
- name: group_id
|
|
in: path
|
|
description: The ID of the group.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
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:
|
|
description: Get all user groups of the realm.
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
user_groups:
|
|
type: array
|
|
items:
|
|
type: object
|
|
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]
|
|
}
|
|
]
|
|
}
|
|
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
|
|
ApiKeyResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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/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"
|
|
}
|
|
InvalidMessageError:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
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/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'
|