zulip/zerver/openapi/zulip.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:
  /events:
    get:
      description: Receive new events from
        [a registered event queue](/api/register-queue).
      parameters:
      - name: queue_id
        in: query
        description: The ID of a queue that you registered via
          `POST /api/v1/register`
          (see [Register a queue](/api/register-queue)).
        schema:
          type: string
        example: 1375801870:2942
      - name: last_event_id
        in: query
        description: The highest event ID in this queue that you've received
          and wish to acknowledge. See the [code for `call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py)
          in the [zulip Python module](https://github.com/zulip/python-zulip-api)
          for an example implementation of correctly processing each event
          exactly once.
        schema:
          type: integer
        example: -1
      - name: dont_block
        in: query
        description: Set to `true` if the client is requesting a nonblocking
          reply. If not specified, the request will block until either a new
          event is available or a few minutes have passed, in which case the
          server will send the client a heartbeat event.
        schema:
          type: boolean
          default: false
        example: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    events:
                      type: array
                      description: An array of `event` objects (possibly
                        zero-length if `dont_block` is set) of events with
                        IDs newer than `last_event_id`. Event IDs are
                        guaranted to be increasing, but they are not
                        guaranteed to be consecutive.
                - example:
                    {
                        "events": [
                            {
                                "id": 0,
                                "message": {
                                    "avatar_url": "https://url/for/othello-bots/avatar",
                                    "client": "website",
                                    "content": "Something is rotten in the state of Denmark.",
                                    "content_type": "text/x-markdown",
                                    "display_recipient": "Denmark",
                                    "id": 12345678,
                                    "recipient_id": 12314,
                                    "sender_email": "othello-bot@example.com",
                                    "sender_full_name": "Othello Bot",
                                    "sender_id": 13215,
                                    "sender_realm_str": "example",
                                    "sender_short_name": "othello-bot",
                                    "subject": "Castle",
                                    "subject_links": [],
                                    "timestamp": 1375978403,
                                    "type": "stream"
                                },
                                "type": "message"
                            },
                            {
                                "id": 1,
                                "message": {
                                    "avatar_url": "https://url/for/othello-bots/avatar",
                                    "client": "website",
                                    "content": "I come not, friends, to steal away your hearts.",
                                    "content_type": "text/x-markdown",
                                    "display_recipient": [
                                        {
                                            "email": "hamlet@example.com",
                                            "full_name": "Hamlet of Denmark",
                                            "id": 31572,
                                            "short_name": "hamlet"
                                        }
                                    ],
                                    "id": 12345679,
                                    "recipient_id": 18391,
                                    "sender_email": "othello-bot@example.com",
                                    "sender_full_name": "Othello Bot",
                                    "sender_id": 13215,
                                    "sender_realm_str": "example",
                                    "sender_short_name": "othello-bot",
                                    "subject": "",
                                    "subject_links": [],
                                    "timestamp": 1375978404,
                                    "type": "private"
                                },
                                "type": "message"
                            }
                        ],
                        "msg": "",
                        "result": "success"
                    }
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadEventQueueIdError'
    delete:
      description: Delete a previously registered queue.
      parameters:
      - name: queue_id
        in: query
        description: The ID of a queue that you registered via
          `POST /api/v1/register`(see [Register a queue](/api/register-queue).
        schema:
          type: string
        example: 1375801870:2942
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadEventQueueIdError'
  /get_stream_id:
    get:
      description: Get the unique ID of a given stream.
      parameters:
      - name: stream
        in: query
        description: The name of the stream to retrieve the ID for.
        schema:
          type: string
        example: Denmark
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    stream_id:
                      type: integer
                      description: The ID of the given stream.
                - example:
                    {
                        "msg": "",
                        "result": "success",
                        "stream_id": 15
                    }
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    {
                        "code": "BAD_REQUEST",
                        "msg": "Invalid stream name 'nonexistent'",
                        "result": "error"
                    }
  /messages:
    post:
      description: Send a message.
      parameters:
      - name: type
        in: query
        description: The type of message to be sent. `private` for a private
          message and `stream` for a stream message.
        schema:
          type: string
          enum:
          - private
          - stream
        example: private
        required: true
      - name: to
        in: query
        description: The destination stream, or a CSV/JSON-encoded list
          containing the usernames (emails) of the recipients.
        schema:
          type: string
        example: aaron@zulip.com, iago@zulip.com
        required: true
      - name: subject
        in: query
        description: The topic of the message. Only required if `type` is
          `stream`, ignored otherwise. Maximum length of 60 characters.
        schema:
          type: string
          default:
        example: Castle
      - name: content
        in: query
        description: The content of the message. Maximum message size of
          10000 bytes.
        schema:
          type: string
        example: Hello
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    id:
                      type: integer
                      description: The ID assigned to the message sent.
                - example:
                    {
                        "msg": "",
                        "id": 42,
                        "result": "success"
                    }
        '400_non_existing_stream':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NonExistingStreamError'
        '400_non_existing_user':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    {
                        "code": "BAD_REQUEST",
                        "msg": "Invalid email 'eeshan@zulip.com'",
                        "result": "error"
                    }
  /messages/{message_id}:
    patch:
      description: Edit a message that has already been sent.
      parameters:
      - name: message_id
        in: path
        description: The ID of the message that you wish to edit/update.
        schema:
          type: integer
        example: 42
        required: true
      - name: subject
        in: query
        description: The topic of the message. Only required for stream
          messages. Maximum length of 60 characters.
        schema:
          type: string
          default:
        example: Castle
      - name: propagate_mode
        in: query
        description: "Which message(s) should be edited: just the one
          indicated in `message_id`, messages in the same topic that had been
          sent after this one, or all of them."
        schema:
          type: string
          enum:
          - change_one
          - change_later
          - change_all
          default: change_one
        example: change_all
      - name: content
        in: query
        description: The content of the message. Maximum message size of 10000
          bytes.
        schema:
          type: string
        example: Hello
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonError'
                - properties:
                    msg:
                      enum:
                      - Your organization has turned off message editing
                      - You don't have permission to edit this message
                      - The time limit for editing this message has past
                      - Nothing to change
                      - Topic can't be empty
                - example:
                    {
                        "code": "BAD_REQUEST",
                        "msg": "You don't have permission to edit this message",
                        "result": "error"
                    }
  /messages/render:
    post:
      description: Render a message to HTML.
      parameters:
      - name: content
        in: query
        description: The content of the message.
        schema:
          type: string
        example: '**foo**'
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    rendered:
                      type: string
                      description: The rendered HTML.
                - example:
                    {
                        "msg": "",
                        "rendered": "<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,
                                "user_id": 1
                            },
                            {
                                "avatar_url": "https://secure.gravatar.com/avatar/77c3871a68c8d70356156029fd0a4999?d=identicon&version=1",
                                "bot_type": null,
                                "email": "cordelia@zulip.com",
                                "full_name": "Cordelia Lear",
                                "is_active": true,
                                "is_admin": false,
                                "is_bot": false,
                                "user_id": 3
                            },
                            {
                                "avatar_url": "https://secure.gravatar.com/avatar/0cbf08f3a355995fa2ec542246e35123?d=identicon&version=1",
                                "bot_type": null,
                                "email": "newbie@zulip.com",
                                "full_name": "New User",
                                "is_active": true,
                                "is_admin": false,
                                "is_bot": false,
                                "user_id": 24
                            }
                        ],
                        "msg": "",
                        "result": "success"
                    }
    post:
      description: Create a new user in a realm.
      parameters:
      - name: email
        in: query
        description: The email address of the new user.
        schema:
          type: string
        example: newbie@zulip.com
        required: true
      - name: password
        in: query
        description: The password of the new user.
        schema:
          type: string
        example: abdec@7982
        required: true
      - name: full_name
        in: query
        description: The full name of the new user.
        schema:
          type: string
        example: John Smith
        required: true
      - name: short_name
        in: query
        description: The short name of the new user.
        schema:
          type: string
        example: jsmith
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonSuccess'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonError'
                - example:
                    {
                        "msg": "Email 'newbie@zulip.com' already in use",
                        "result": "error"
                    }
  /users/me/{stream_id}/topics:
    get:
      description: Get all the topics in a specific stream.
      parameters:
      - name: stream_id
        in: path
        description: The unique ID of the stream.
        schema:
          type: integer
        example: 42
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    topics:
                      type: array
                      items:
                        type: object
                        properties:
                          max_id:
                            description:
                              The ID of the last message sent to the topic.
                            type: number
                          name:
                            description: The name of the topic.
                            type: string
                - example:
                    {
                        "msg": "",
                        "result": "success",
                        "topics": [
                            {
                                "max_id": 26,
                                "name": "Denmark3"
                            },
                            {
                                "max_id": 23,
                                "name": "Denmark1"
                            },
                            {
                                "max_id": 6,
                                "name": "Denmark2"
                            }
                        ]
                    }
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonError'
                - example:
                    {
                        "code": "BAD_REQUEST",
                        "msg": "Invalid stream id",
                        "result": "error"
                    }
  /users/me/subscriptions:
    post:
      description: Subscribe one or more users to one or more streams.
      parameters:
      - name: subscriptions
        in: query
        description: "A list of dictionaries, where each dictionary contains
          key/value pairs specifying a particular stream to subscribe to.
          **Note**: This argument is called `streams` and not `subscriptions`
          in our Python API."
        schema:
          type: array
          items:
            type: object
        example: [{"name": "Verona"}]
        required: true
      - name: invite_only
        in: query
        description: A boolean specifying whether the streams specified in
          `subscriptions` are invite-only or not.
        schema:
          type: boolean
          default: false
        example: true
      - name: announce
        in: query
        description: If `announce` is `True` and one of the streams specified
          in `subscriptions` has to be created (i.e. doesn't exist to begin
          with), an announcement will be made notifying that a new stream was
          created.
        schema:
          type: boolean
        example: true
      - name: principals
        in: query
        description: A list of email addresses of the users that will be
          subscribed to the streams specified in the `subscriptions` argument.
          If not provided, then the requesting user/bot is subscribed.
        schema:
          type: array
          items:
            type: string
          default: []
        example: ['ZOE@zulip.com']
      - name: authorization_errors_fatal
        in: query
        description: A boolean specifying whether authorization errors (such
          as when the requesting user is not authorized to access a private
          stream) should be considered fatal or not. When `True`, an
          authorization error is reported as such. When set to `False`, the
          returned JSON payload indicates that there was an authorization
          error, but the response is still considered a successful one.
        schema:
          type: boolean
          default: true
        example: false
      security:
      - basicAuth: []
      responses:
        '200_without_principals':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AddSubscriptionsResponse'
                - example:
                    {
                        "already_subscribed": {},
                        "msg": "",
                        "result": "success",
                        "subscribed": {
                            "iago@zulip.com": [
                                "new stream"
                            ]
                        }
                    }
        '200_already_subscribed':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AddSubscriptionsResponse'
                - example:
                    {
                        "already_subscribed": {
                            "newbie@zulip.com": [
                                "new stream"
                            ]
                        },
                        "msg": "",
                        "result": "success",
                        "subscribed": {}
                    }
        '400_unauthorized_errors_fatal_true':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AddSubscriptionsResponse'
                - example:
                    {
                        "msg": "Unable to access stream (private_stream).",
                        "result": "error"
                    }
        '400_unauthorized_errors_fatal_false':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/AddSubscriptionsResponse'
                - example:
                    {
                        "already_subscribed": {},
                        "msg": "",
                        "result": "success",
                        "subscribed": {},
                        "unauthorized": [
                            "private_stream"
                        ]
                    }
    delete:
      description: Unsubscribe yourself or other users from one or more
        streams.
      parameters:
      - name: subscriptions
        in: query
        description: A list of stream names to unsubscribe from. This argument
          is called `streams` in our Python API.
        schema:
          type: array
          items:
            type: string
        example: ['Verona', 'Denmark']
        required: true
      - name: principals
        in: query
        description: A list of email addresses of the users that will be
          unsubscribed from the streams specified in the `subscriptions`
          argument. If not provided, then the requesting user/bot is
          unsubscribed.
        schema:
          type: array
          items:
            type: string
          default:
        example: ['ZOE@zulip.com']
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    not_subscribed:
                      type: array
                      items:
                        type: string
                      description: A list of the names of streams that the
                        user is already unsubscribed from, and hence doesn't
                        need to be unsubscribed.
                    removed:
                      type: array
                      items:
                        type: string
                      description: A list of the names of streams which were
                        unsubscribed from as a result of the query.
                - example:
                    {
                        "msg": "",
                        "not_subscribed": [],
                        "removed": [
                            "new stream"
                        ],
                        "result": "success"
                    }
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NonExistingStreamError'
  /register:
    post:
      description: This powerful endpoint can be used to register a Zulip
        "event queue" (subscribed to certain types of "events", or updates to
        the messages and other Zulip data the current user has access to), as
        well as to fetch the current state of that data.
      parameters:
      - name: apply_markdown
        in: query
        description: Set to `true` if you would like the content to be
          rendered in HTML format (by default, the API returns the raw text
          that the user entered)
        schema:
          type: boolean
          default: false
        example: true
      - name: client_gravatar
        in: query
        description: The `client_gravatar` field is set to `true` if clients
          can compute their own gravatars.
        schema:
          type: boolean
          default: false
        example: true
      - name: event_types
        in: query
        description: "A JSON-encoded array indicating which types of events
          you're interested in. Values that you might find useful include:
          <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"
                    }
  /streams:
    get:
      description: Get all streams that the user has access to.
      parameters:
      - name: include_public
        in: query
        description: Include all public streams.
        schema:
          type: boolean
          default: true
        example: false
      - name: include_subscribed
        in: query
        description: Include all streams that the user is subscribed to.
        schema:
          type: boolean
          default: true
        example: false
      - name: include_all_active
        in: query
        description: Include all active streams. The user must have
          administrative privileges to use this parameter.
        schema:
          type: boolean
          default: false
        example: true
      - name: include_default
        in: query
        description: Include all default streams for the user's realm.
        schema:
          type: boolean
          default: false
        example: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccess'
                - properties:
                    streams:
                      type: array
                      items:
                        type: object
                      description: A list of `stream` objects, which contain a
                        `description`, a `name`, their `stream_id` and whether
                        they are `invite_only` or not.
                - example:
                    {
                        "msg": "",
                        "result": "success",
                        "streams": [
                            {
                                "description": "A Scandinavian country",
                                "invite_only": false,
                                "name": "Denmark",
                                "stream_id": 1
                            },
                            {
                                "description": "Yet another Italian city",
                                "invite_only": false,
                                "name": "Rome",
                                "stream_id": 2
                            },
                            {
                                "description": "Located in the United Kingdom",
                                "invite_only": false,
                                "name": "Scotland",
                                "stream_id": 3
                            },
                            {
                                "description": "A northeastern Italian city",
                                "invite_only": false,
                                "name": "Venice",
                                "stream_id": 4
                            },
                            {
                                "description": "A city in Italy",
                                "invite_only": false,
                                "name": "Verona",
                                "stream_id": 5
                            },
                            {
                                "description": "New stream for testing",
                                "invite_only": false,
                                "name": "new stream",
                                "stream_id": 6
                            }
                        ]
                    }
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    {
                        "code": "BAD_REQUEST",
                        "msg": "User not authorized for this query",
                        "result": "error"
                    }

components:
  #######################
  # Security definitions
  #######################
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication, with the user's email as the
        username, and the API key as the password. The API key can be fetched
        using the `/fetch_api_key` or `/dev_fetch_api_key` endpoints.

  schemas:
    JsonResponse:
      type: object
      properties:
        result:
          type: string
    JsonSuccess:
      allOf:
      - $ref: '#/components/schemas/JsonResponse'
      - required:
        - result
        - msg
      - properties:
          result:
            enum:
            - success
          msg:
            type: string
      - example:
          {
            "msg": "",
            "result": "success"
          }
    JsonError:
      allOf:
      - $ref: '#/components/schemas/JsonResponse'
      - required:
        - result
        - msg
      - properties:
          result:
            enum:
            - error
          msg:
            type: string
    CodedError:
      allOf:
      - $ref: '#/components/schemas/JsonError'
      - properties:
          code:
            type: string
            description: A string that identifies the error.
    BadEventQueueIdError:
      allOf:
      - $ref: '#/components/schemas/CodedError'
      - properties:
          queue_id:
            type: string
            description: The string that identifies the invalid event queue.
      - example:
          {
              "code": "BAD_EVENT_QUEUE_ID",
              "msg": "Bad event queue id: 1518820930:1",
              "queue_id": "1518820930:1",
              "result": "error"
          }
    NonExistingStreamError:
      allOf:
        - $ref: '#/components/schemas/CodedError'
        - properties:
            stream:
              type: string
              description: The name of the stream that could not be
                found.
        - example:
            {
                "code": "STREAM_DOES_NOT_EXIST",
                "msg": "Stream 'nonexistent_stream' does not exist",
                "result": "error",
                "stream": "nonexistent_stream"
            }
    AddSubscriptionsResponse:
      allOf:
      - $ref: '#/components/schemas/JsonSuccess'
      - properties:
          subscribed:
            type: object
            description: A dictionary where the key is the email address of
              the user/bot and the value is a list of the names of the streams
              that were subscribed to as a result of the query.
          already_subscribed:
            type: object
            description: A dictionary where the key is the email address of
              the user/bot and the value is a list of the names of the streams
              that the user/bot is already subscribed to.
          unauthorized:
            type: array
            items:
              type: string
            description: A list of names of streams that the requesting
              user/bot was not authorized to subscribe to.

  ###################
  # Shared responses
  ###################
  responses:
    SimpleSuccess:
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'