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

2118 lines
75 KiB
YAML
Raw Normal View History

api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
# This file contains the API definitions for the Zulip REST API.
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
#
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
# For details on the OpenAPI specification, see http://swagger.io/specification
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
# Our own documentation lives at
#
docs: Rename Swagger to OpenAPI in the dev docs' titles.
2018-05-15 20:54:48 +02:00
# https://zulip.readthedocs.io/en/latest/subsystems/openapi-api-docs.html
Explain how to add Swagger REST API doc coverage in zulip.yaml. Introduce Swagger UI and the Swagger/OpenAPI specification. Explain the structure of zulip.yaml and show examples of different sections of the file. This is a new file in /docs not yet included in the Read the Docs table of contents. Where it should go should be determined as we iterate on the Swagger UI integration and expand REST API doc coverage using it. For more on Swagger UI and how Zulip uses it, see: https://github.com/zulip/zulip/issues/3474 https://github.com/zulip/zulip/pull/3397 With some minor tweaks to advertise this by tabbott.
2017-02-24 03:39:44 +01:00
#
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
openapi: 3.0.1
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
info:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
version: 1.0.0
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
title: Zulip REST API
description: Powerful open source group chat
contact:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
url: https://zulipchat.com
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
servers:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
- url: 'https://your.zulip.server/api/v1'
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
# Endpoint definitions
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
#######################
api: Add Swagger YAML file. Authored-By: Andrea Longo
2017-05-22 18:33:53 +02:00
paths:
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
/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'
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
/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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
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",
api docs: Change Shakespeare quote. The previous quote doesn't come off well if you don't know the reference (which the majority of our users will not).
2018-10-23 00:42:54 +02:00
"content": "I come not, friends, to steal away your hearts.",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"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",
api docs: Change Shakespeare quote. The previous quote doesn't come off well if you don't know the reference (which the majority of our users will not).
2018-10-23 00:42:54 +02:00
"content": "With mirth and laughter let old wrinkles come.",
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
"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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Bad request.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
content:
application/json:
schema:
$ref: '#/components/schemas/BadEventQueueIdError'
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
delete:
description: Delete a previously registered queue.
parameters:
- name: queue_id
in: query
description: The ID of a queue that you registered via
api docs: Remove unnecessary link.
2018-08-01 12:41:47 +02:00
`POST /api/v1/register`(see [Register a queue](/api/register-queue).
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate DELETE /events to OpenAPI.
2018-06-21 01:28:33 +02:00
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'
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
/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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
example: Denmark
required: true
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Bad request.
api docs: Migrate GET /get_stream_id to OpenAPI.
2018-06-18 19:20:55 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
"result": "error"
}
api docs: Document POST /mark_(all|stream|topic)_as_read.
2018-08-11 13:38:55 +02:00
/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'
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
/messages:
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
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.
messages: Add history_limited flag to messages response. The purpose of this commit is to pass information to the frontend whether the message response recieved has been limited due to plan restrictions or not. To implement this, the backend for limiting the message history had to be rewritten as we used to fetch only the message rows whose id was greater than first_visible_message_id. The filtered rows gives us no information on whether the message history was limited or not. So the backend was rewritten to not do any restriction of limiting the message rows while making the query. The limiting of rows is now done in post_process_limited_query which will also return back the value of history_limited flag. Tweaked by tabbott to note a few cases where the results are incorrect. I'm merging this despite those, because those cases don't impact the correctness of the feature, and it may have tricky performance implications to fix correctly.
2018-09-19 14:23:02 +02:00
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.
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
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": []
}
]
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
- private
- stream
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
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:
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
$ref: '#/components/schemas/NonExistingStreamError'
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
'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"
}
docs: Document /get_stream_id API endpoint.
2017-06-25 21:00:55 +02:00
/messages/{message_id}:
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
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'
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
patch:
description: Edit a message that has already been sent.
parameters:
- name: message_id
in: path
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
description: The ID of the message that you wish to edit/update.
schema:
type: integer
example: 42
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
required: true
- name: subject
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: The topic of the message. Only required for stream
messages. Maximum length of 60 characters.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schema:
type: string
default:
example: Castle
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
- name: propagate_mode
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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."
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schema:
type: string
enum:
- change_one
- change_later
- change_all
default: change_one
example: change_all
docs: Sort REST API endpoints alphabetically.
2017-06-25 16:50:27 +02:00
- name: content
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: The content of the message. Maximum message size of 10000
bytes.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schema:
type: string
example: Hello
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
content:
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'
docs: Document /streams/{stream_id} API endpoint.
2017-06-27 03:48:27 +02:00
'400':
description: Bad request.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
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
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"code": "BAD_REQUEST",
"msg": "You don't have permission to edit this message",
"result": "error"
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
}
api docs: Document the DELETE /messages/<message_id> endpoint.
2018-06-26 16:30:46 +02:00
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"
}
api docs: Document the GET /messages/<message_id>/history endpoint.
2018-06-27 22:54:08 +02:00
/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'
api docs: Document the POST /messages/flags endpoint.
2018-07-03 18:17:23 +02:00
/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
enum:
- read
- starred
- collapsed
- mentioned
- wildcard_mentioned
- summarize_in_home
- summarize_in_stream
- force_expand
- force_collapse
- has_alert_word
- historical
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"
}
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
/messages/render:
post:
description: Render a message to HTML.
parameters:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
- name: content
in: query
description: The content of the message.
schema:
type: string
example: '**foo**'
required: true
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /messages/render to OpenAPI.
2018-06-18 19:29:12 +02:00
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"
}
api docs: Migrate POST /user_uploads to OpenAPI.
2018-06-21 03:04:05 +02:00
/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"
}
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
/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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
example: true
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
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,
api_docs: Document is_guest field in the get_members API.
2019-01-23 07:41:29 +01:00
"is_guest": false,
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
"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,
api_docs: Document is_guest field in the get_members API.
2019-01-23 07:41:29 +01:00
"is_guest": false,
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
"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,
api_docs: Document is_guest field in the get_members API.
2019-01-23 07:41:29 +01:00
"is_guest": true,
api docs: Migrate GET /users to OpenAPI.
2018-06-18 19:43:40 +02:00
"user_id": 24
}
],
"msg": "",
"result": "success"
}
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
post:
description: Create a new user in a realm.
parameters:
- name: email
in: query
description: The email address of the new user.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
example: newbie@zulip.com
required: true
- name: password
in: query
description: The password of the new user.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
example: abdec@7982
required: true
- name: full_name
in: query
description: The full name of the new user.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
example: John Smith
required: true
- name: short_name
in: query
description: The short name of the new user.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate POST /users to OpenAPI.
2018-06-21 01:47:22 +02:00
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"
}
api docs: Document GET /users/<email>/presence. Tweaked by tabbott to describe more clearly what this is for.
2018-08-07 17:52:03 +02:00
/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": ""
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
/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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
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:
{
api docs: Fix indentation.
2018-06-06 18:17:58 +02:00
"msg": "",
"result": "success",
"topics": [
{
"max_id": 26,
"name": "Denmark3"
},
{
"max_id": 23,
"name": "Denmark1"
},
{
"max_id": 6,
"name": "Denmark2"
}
]
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonError'
- example:
{
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
"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
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: "A list of dictionaries, where each dictionary contains
key/value pairs specifying a particular stream to subscribe to.
api: Document support for setting stream description on creation. This makes clear how to set the stream description when making a new stream. Fixes #11372.
2019-01-29 20:20:58 +01:00
You can specify an initial description here when creating a new stream.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
**Note**: This argument is called `streams` and not `subscriptions`
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
in our Python API."
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: array
api docs: Specify array types.
2018-06-21 02:18:05 +02:00
items:
type: object
api: Document support for setting stream description on creation. This makes clear how to set the stream description when making a new stream. Fixes #11372.
2019-01-29 20:20:58 +01:00
example: [{"name": "Verona", "description": "Italian City"}]
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
required: true
- name: invite_only
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: A boolean specifying whether the streams specified in
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
`subscriptions` are invite-only or not.
schema:
type: boolean
default: false
example: true
- name: announce
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: If `announce` is `True` and one of the streams specified
in `subscriptions` has to be created (i.e. doesn't exist to begin
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
with), an announcement will be made notifying that a new stream was
created.
schema:
type: boolean
example: true
- name: principals
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: array
api docs: Specify array types.
2018-06-21 02:18:05 +02:00
items:
type: string
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
default: []
example: ['ZOE@zulip.com']
- name: authorization_errors_fatal
in: query
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
schema:
type: boolean
default: true
example: false
security:
- basicAuth: []
responses:
'200_without_principals':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {
"iago@zulip.com": [
"new stream"
]
}
api docs: Document the /users/me/<stream_id>/topics endpoint.
2018-06-01 18:58:07 +02:00
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
'200_already_subscribed':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
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':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"msg": "Unable to access stream (private_stream).",
"result": "error"
}
'400_unauthorized_errors_fatal_false':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddSubscriptionsResponse'
- example:
{
"already_subscribed": {},
"msg": "",
"result": "success",
"subscribed": {},
"unauthorized": [
"private_stream"
]
}
api docs: Migrate DELETE /users/me/subscriptions to OpenAPI.
2018-06-21 02:23:47 +02:00
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:
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
$ref: '#/components/schemas/NonExistingStreamError'
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
/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:
{
muting: Correct agrammatical error message. The error message displayed when unmuting a topic that wasn't previously muted wasn't properly formulated.
2018-08-27 22:13:56 +02:00
"msg": "Topic is not muted",
api docs: Document the PATCH /users/me/subscriptions/muted_topics endpoint.
2018-07-10 08:17:35 +02:00
"result": "error"
}
api docs: Document the custom emoji upload endpoint. Tweaked by tabbott to fix some English phrasing and make the file pointer thing require less Python knowledge. Fixes: #10746.
2018-12-12 19:49:14 +01:00
/realm/emoji/<emoji_name>:
post:
description: Upload a single emoji file.
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'
api: Document the GET /realm/emoji endpoint.
2018-07-03 20:22:53 +02:00
/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"
}
}
}
}
api docs: Document the POST /users/me/subscriptions/properties endpoint.
2018-07-12 10:09:50 +02:00
/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": ""
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
/realm/filters:
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
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
linkifiers: Rename articles to current feature name. These were previously called "linkification filters", but we now want to consistently refer to them as "linkifiers" in the UI and API docs.
2018-10-16 21:01:17 +02:00
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.
api docs: Document GET /realm/filters.
2018-08-14 03:10:37 +02:00
- example:
{
"msg": "",
"filters": [
[
"#(?P<id>[0-9]+)",
"https://github.com/zulip/zulip/issues/%(id)s",
1
]
],
"result": "success"
}
api docs: Document POST /realm/filters.
2018-08-14 02:54:36 +02:00
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": ""
}
api docs: Document DELETE /realm/filters/<filter_id>.
2018-08-14 03:20:39 +02:00
/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'
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
/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
api docs: Document the GET /messages endpoint.
2018-06-23 17:31:12 +02:00
rendered in HTML format (otherwise the API will return the raw text
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
that the user entered)
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
example: true
- name: client_gravatar
in: query
description: The `client_gravatar` field is set to `true` if clients
can compute their own gravatars.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: string
default: narrow=[]
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
example: narrow=['stream', 'Denmark']
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate /register to OpenAPI.
2018-06-20 23:03:01 +02:00
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"
}
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
/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.
compatibility: Add a compatibility check to api_get_server_settings. This should make it convenient for the mobile app to present errors of the form "Your Zulip app is not new enough for this Zulip server".
2018-12-06 02:49:34 +01:00
is_incompatible:
type: boolean
description: Whether the Zulip client that has sent a
request to this endpoint is deemed incompatible with
the server.
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
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
docs: Move LDAP documentation out of plug-and-play section. Also update the links to this section.
2018-09-27 22:35:57 +02:00
[LDAP authentication](https://zulip.readthedocs.io/en/latest/production/authentication-methods.html#ldap-including-active-directory)
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
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
settings: Add support for customizing the top-left logo. This adds a new realm_logo field, which is a horizontal-format logo to be displayed in the top-left corner of the webapp, and any other places where we might want a wide-format branding of the organization. Tweaked significantly by tabbott to rebase, fix styling, etc. Fixing the styling of this feature's loading indicator caused me to notice the loading indicator for the realm_icon feature was also ugly, so I fixed that too. Fixes #7995.
2018-08-16 01:26:55 +02:00
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).
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
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",
settings: Add support for customizing the top-left logo. This adds a new realm_logo field, which is a horizontal-format logo to be displayed in the top-left corner of the webapp, and any other places where we might want a wide-format branding of the organization. Tweaked significantly by tabbott to rebase, fix styling, etc. Fixing the styling of this feature's loading indicator caused me to notice the loading indicator for the realm_icon feature was also ugly, so I fixed that too. Fixes #7995.
2018-08-16 01:26:55 +02:00
"realm_logo": "/static/images/logo/zulip-org-logo.png",
api docs: Document GET /server_settings.
2018-08-11 15:50:56 +02:00
"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
}
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
/streams:
get:
description: Get all streams that the user has access to.
parameters:
- name: include_public
in: query
description: Include all public streams.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: false
- name: include_subscribed
in: query
description: Include all streams that the user is subscribed to.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: true
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: false
- name: include_all_active
in: query
description: Include all active streams. The user must have
administrative privileges to use this parameter.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: true
- name: include_default
in: query
description: Include all default streams for the user's realm.
schema:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
type: boolean
default: false
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
example: true
security:
- basicAuth: []
responses:
'200':
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
api docs: Migrate GET /streams to OpenAPI.
2018-06-18 18:53:13 +02:00
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"
}
api docs: Document POST /typing.
2018-08-09 20:27:12 +02:00
/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: notification_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'
api: Add GET /user_groups documentation. This documents our GET endpoint for interacting with Zulip's user groups feature. Fixes #10298.
2018-08-18 23:06:53 +02:00
/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]
}
]
}
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
components:
#######################
# Security definitions
#######################
securitySchemes:
BasicAuth:
type: http
scheme: basic
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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.
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
schemas:
JsonResponse:
type: object
properties:
docs: Amend definitions of JSON responses.
2017-06-25 17:52:59 +02:00
result:
docs: Fix JsonSuccess and JsonError models.
2017-05-24 05:22:50 +02:00
type: string
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonSuccess:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- success
msg:
type: string
api docs: Read parameters and response fixtures from OpenAPI files.
2018-05-15 19:28:42 +02:00
- example:
{
"msg": "",
"result": "success"
}
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
JsonError:
allOf:
- $ref: '#/components/schemas/JsonResponse'
- required:
- result
- msg
- properties:
result:
enum:
- error
msg:
type: string
api docs: Document the /dev_fetch_api_key endpoint.
2018-06-21 15:23:10 +02:00
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"
}
api docs: Migrate POST /messages to OpenAPI.
2018-06-18 18:15:08 +02:00
CodedError:
allOf:
- $ref: '#/components/schemas/JsonError'
- properties:
code:
type: string
description: A string that identifies the error.
api docs: Migrate GET /events to OpenAPI.
2018-06-21 01:05:11 +02:00
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"
}
api docs: Document the GET /messages/<message_id> endpoint.
2018-06-23 18:17:05 +02:00
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"
}
api docs: Create the NonExistingStreamError schema definition.
2018-06-21 02:25:29 +02:00
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"
}
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
AddSubscriptionsResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
subscribed:
type: object
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
already_subscribed:
type: object
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
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.
api docs: Migrate POST /users/me/subscriptions to OpenAPI.
2018-06-07 19:47:49 +02:00
unauthorized:
type: array
items:
type: string
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: A list of names of streams that the requesting
user/bot was not authorized to subscribe to.
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
###################
# Shared responses
###################
responses:
SimpleSuccess:
api docs: Minor formatting improvements.
2018-06-21 02:03:15 +02:00
description: Success.
docs: Document /messages API endpoint.
2017-05-24 01:54:20 +02:00
content:
api docs: Create new file for OpenAPI 3.0 docs. To make the Swagger to OpenAPI transition easier, the old Swagger file will remain as the endpoints are converted to the new format.
2018-05-15 18:55:39 +02:00
application/json:
schema:
$ref: '#/components/schemas/JsonSuccess'