mirror of https://github.com/zulip/zulip.git
372 lines
12 KiB
YAML
372 lines
12 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/subsystems/openapi-api-docs.html
|
|
#
|
|
|
|
openapi: 3.0.1
|
|
info:
|
|
version: 1.0.0
|
|
title: Zulip REST API
|
|
description: Powerful open source group chat
|
|
contact:
|
|
url: https://zulipchat.com
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
servers:
|
|
- url: 'https://your.zulip.server/api/v1'
|
|
|
|
#######################
|
|
# Endpoint definitions
|
|
#######################
|
|
paths:
|
|
/messages/{message_id}:
|
|
patch:
|
|
description: Edit a message that has already been sent.
|
|
parameters:
|
|
- name: message_id
|
|
in: path
|
|
description: The ID of the message that you wish to edit/update.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
- name: subject
|
|
in: query
|
|
description: |
|
|
The topic of the message. Only required for stream messages.
|
|
Maximum length of 60 characters.
|
|
schema:
|
|
type: string
|
|
default:
|
|
example: Castle
|
|
- name: propagate_mode
|
|
in: query
|
|
description: |
|
|
Which message(s) should be edited: just the one indicated in
|
|
`message_id`, messages in the same topic that had been sent after
|
|
this one, or all of them.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- change_one
|
|
- change_later
|
|
- change_all
|
|
default: change_one
|
|
example: change_all
|
|
- name: content
|
|
in: query
|
|
description: |
|
|
The content of the message. Maximum message size of 10000 bytes.
|
|
schema:
|
|
type: string
|
|
example: Hello
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JsonSuccess'
|
|
'400':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonError'
|
|
- properties:
|
|
msg:
|
|
enum:
|
|
- Your organization has turned off message editing
|
|
- You don't have permission to edit this message
|
|
- The time limit for editing this message has past
|
|
- Nothing to change
|
|
- Topic can't be empty
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "You don't have permission to edit this message",
|
|
"result": "error"
|
|
}
|
|
/users/me/{stream_id}/topics:
|
|
get:
|
|
description: Get all the topics in a specific stream.
|
|
parameters:
|
|
- name: stream_id
|
|
in: path
|
|
description: The unique ID of the stream.
|
|
schema:
|
|
type: integer
|
|
example: 42
|
|
required: true
|
|
security:
|
|
- basicAuth: []
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonSuccess'
|
|
- properties:
|
|
topics:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
max_id:
|
|
description:
|
|
The ID of the last message sent to the topic.
|
|
type: number
|
|
name:
|
|
description: The name of the topic.
|
|
type: string
|
|
- example:
|
|
{
|
|
"msg": "",
|
|
"result": "success",
|
|
"topics": [
|
|
{
|
|
"max_id": 26,
|
|
"name": "Denmark3"
|
|
},
|
|
{
|
|
"max_id": 23,
|
|
"name": "Denmark1"
|
|
},
|
|
{
|
|
"max_id": 6,
|
|
"name": "Denmark2"
|
|
}
|
|
]
|
|
}
|
|
'400':
|
|
description: Bad request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/JsonError'
|
|
- example:
|
|
{
|
|
"code": "BAD_REQUEST",
|
|
"msg": "Invalid stream id",
|
|
"result": "error"
|
|
}
|
|
/users/me/subscriptions:
|
|
post:
|
|
description: Subscribe one or more users to one or more streams.
|
|
parameters:
|
|
- name: subscriptions
|
|
in: query
|
|
description: |
|
|
A list of dictionaries, where each dictionary contains key/value
|
|
pairs specifying a particular stream to subscribe to.
|
|
**Note**: This argument is called `streams` and not `subscriptions`
|
|
in our Python API.
|
|
schema:
|
|
type: string
|
|
example: [{"name": "Verona"}]
|
|
required: true
|
|
- name: invite_only
|
|
in: query
|
|
description: |
|
|
A boolean specifying whether the streams specified in
|
|
`subscriptions` are invite-only or not.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
example: true
|
|
- name: announce
|
|
in: query
|
|
description: |
|
|
If `announce` is `True` and one of the streams specified in
|
|
`subscriptions` has to be created (i.e. doesn't exist to begin
|
|
with), an announcement will be made notifying that a new stream was
|
|
created.
|
|
schema:
|
|
type: boolean
|
|
example: true
|
|
- name: principals
|
|
in: query
|
|
description: |
|
|
A list of email addresses of the users that will be subscribed to
|
|
the streams specified in the `subscriptions` argument. If not
|
|
provided, then the requesting user/bot is subscribed.
|
|
schema:
|
|
type: 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"
|
|
]
|
|
}
|
|
|
|
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
|
|
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'
|