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:
  /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'