zulip/zerver/openapi/zulip-2.0.yaml

# THIS FILE IS DEPRECATED! Please refer to zulip.yaml, which contains the new
# specification (using OpenAPI 3.0).
#
# The current contents of this file should be reviewed and migrated to the new
# zulip.yaml.

# This file contains the Swagger UI configuration and API definitions
# for the Zulip REST API.
#
# For details on the Swagger/OpenAPI specification, see http://swagger.io/specification
#
# Our own documentation lives at
#
#   https://zulip.readthedocs.io/en/latest/documentation/openapi.html
#
# Basic Swagger UI info
swagger: '2.0'
info:
  version: '1.0.0'
  title: Zulip REST API
  description: Powerful open source group chat
  contact:
    url: https://zulip.org/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

# Backend host to use for API examples.
# This defaults to the Swagger UI host,
# which in this case is also the Zulip host.
#host: 10.2.3.4:9991

# The base configuration for this API
basePath: /api/v1
schemes:
- http
- https
consumes:
- application/x-www-form-urlencoded
produces:
- application/json

######################
# Endpoint definitions

paths:

  /fetch_api_key:
    post:
      description: |
                   Gather a token bound to a user account, to identify and
                   authenticate them when making operations in the API.

                   This token must be used as the password in the rest of the
                   endpoints that require Basic authentication.
      operationId: zerver.views.auth.api_fetch_api_key
      parameters:
      - name: username
        in: formData
        description: The email address for the user that owns the API key.
        required: true
        type: string
      - name: password
        in: formData
        description: The password for the account of the API key's owner.
        required: true
        type: string
      responses:
        '200':
          description: Success.
          schema:
            allOf:
            - $ref: '#/definitions/JsonSuccess'
            - required:
              - api_key
              - email
            - properties:
                api_key:
                  type: string
                  example: c2hvdWxuJ3QgdSBiZSB3b3JraW5nPzsp
                email:
                  description: |
                               The email address for the user that owns the API
                               key.
                  type: string
                  example: iago@zulip.com
                msg:
                  enum:
                    - ''

  /streams/{stream_id}:
    patch:
      description: Update a stream's name, description or privacy setting.
      operationId: zerver.views.streams.update_stream_backend
      parameters:
      - name: stream_id
        in: path
        description: The ID of the stream to modify.
        required: true
        type: integer
      - name: new_name
        in: formData
        description: |
                     New name for the stream.

                     Must be a valid JSON string (enclosed in double quotes and
                     special characters escaped with backslashes).
        type: string
      - name: description
        in: formData
        description: |
                     New description for the stream.

                     Must be a valid JSON string (enclosed in double quotes and
                     special characters escaped with backslashes).
        type: string
      - name: is_private
        in: formData
        description: New privacy setting for the stream.
        type: boolean
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/JsonSuccess'
        '400':
          description: Bad request.
          schema:
            allOf:
            - $ref: '#/definitions/JsonError'
            - properties:
                msg:
                  enum:
                  - Argument "new_name" is not valid JSON.
                  - Argument "description" is not valid JSON.
                  - '"new_name" is not a string'
                  - '"description" is not a string'
                  - '"is_private" is not a boolean'
                  - Stream already has that name!
                  # API_FIXME: There's no error for when the stream already has
                  # the specified description or privacy setting.
    delete:
      description: |
                   Delete a stream.

                   The result is the stream deactivation; its messages will
                   remain in the database, but they won't be recoverable
                   through the API.
      operationId: zerver.views.streams.deactivate_stream_backend
      parameters:
      - name: stream_id
        in: path
        description: The ID of the stream to delete.
        required: true
        type: integer
      security:
        - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/JsonSuccess'
        '400':
          description: Bad request.
          schema:
            allOf:
            - $ref: '#/definitions/JsonError'
            - properties:
                msg:
                  enum:
                  - 'Invalid stream id'

  /users/me/subscriptions:
    get:
      description: List streams subscription data for the current user.
      operationId: zerver.views.streams.list_subscriptions_backend
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            type: object
            required:
            - msg
            - result
            - subscriptions
            properties:
              msg:
                type: string
              result:
                type: string
              subscriptions:
                type: array
                items:
                  $ref: '#/definitions/stream'
    patch:
      description: |
                   Bulk modifies (add or delete) streams subscription data
                   for the current user.
      operationId: zerver.views.streams.update_subscriptions_backend
      parameters:
      - name: delete
        in: formData
        description: |
                     Serialized JSON list of streams to delete. See the
                     `subscriptions` parameter in the POST method for
                     details about the format.
        type: string
      - name: add
        in: formData
        description: |
                     Serialized JSON list of streams to add. See the
                     `subscriptions` parameter in the POST method for
                     details about the format.
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            type: object
            required:
            - subscribed
            - not_subscribed
            - result
            - msg
            - already_subscribed
            - removed
            properties:
              subscribed:
                type: object
                properties:
                  subscriber:
                    type: array
                    items:
                      type: string
              not_subscribed:
                type: array
                items:
                  type: string
              result:
                type: string
              msg:
                type: string
              already_subscribed:
                type: object
                properties:
                  subscriber:
                    type: array
                    items:
                      type: string
              removed:
                type: array
                items:
                  type: string

#######################
# Security definitions
#######################
securityDefinitions:
  basicAuth:
    type: 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.

####################
# Shared definitions
definitions:
  JsonResponse:
    type: object
    properties:
      result:
        type: string

  JsonSuccess:
    allOf:
    - $ref: '#/definitions/JsonResponse'
    - required:
      - result
      - msg
    - properties:
        result:
          enum:
          - success
        msg:
          type: string

  JsonError:
    allOf:
    - $ref: '#/definitions/JsonResponse'
    - required:
      - result
      - msg
    - properties:
        result:
          enum:
          - error
        msg:
          type: string

  # /register
  RegisterResponse:
    type: object
    required:
    - msg
    - result
    - queue_id
    - last_event_id
    properties:
      msg:
        type: string
      result:
        type: string
      queue_id:
        type: string
      last_event_id:
        type: integer
        format: int64
      alert_words:
        type: string
      attachments:
        type: string
      default_language:
        type: string
      enable_desktop_notifications:
        type: boolean
      enable_digest_emails:
        type: boolean
      enable_offline_email_notifications:
        type: boolean
      enable_offline_push_notifications:
        type: boolean
      enable_online_push_notifications:
        type: boolean
      enable_sounds:
        type: boolean
      enable_stream_desktop_notifications:
        type: boolean
      enable_stream_audible_notifications:
        type: boolean
      left_side_userlist:
        type: boolean
      max_message_id:
        type: integer
        format: int64
      muted_topics:
        type: string
      never_subscribed:
        type: array
        items:
          $ref: '#/definitions/stream'
      pointer:
        type: integer
        format: int64
      presences:
        type: string
      realm_add_emoji_by_admins_only:
        type: boolean
      realm_allow_message_deleting:
        type: boolean
      realm_allow_message_editing:
        type: boolean
      realm_authentication_methods:
        type: string
      realm_bots:
        type: string
      realm_create_stream_policy:
        type: int64
      realm_invite_to_stream_policy:
        type: int64
      realm_private_message_policy:
        type: int64
      realm_default_language:
        type: string
      realm_default_streams:
        type: array
        items:
          $ref: '#/definitions/stream'
      realm_domain:
        type: string
      realm_domains:
        type: string
      realm_emoji:
        type: string
      realm_filters:
        type: string
      realm_invite_by_admins_only:
        type: boolean
      realm_invite_required:
        type: boolean
      realm_message_content_edit_limit_seconds:
        type: integer
        format: int64
      realm_message_content_delete_limit_seconds:
        type: integer
        format: int64
      realm_name:
        type: string
      realm_emails_restricted_to_domains:
        type: boolean
      realm_users:
        type: array
        items:
          $ref: '#/definitions/user'
      realm_waiting_period_threshold:
        type: integer
        format: int64
      streams:
        type: array
        items:
          $ref: '#/definitions/stream'
      twenty_four_hour_time:
        type: boolean
      unsubscribed:
        type: string

  # /messages GET
  MessagesResponse:
    type: object
    required:
      - msg
      - result
      - messages
    properties:
      msg:
        type: string
      result:
        type: string
      messages:
        type: array
        items:
          $ref: '#/definitions/message'

  # /messages POST
  MessageResponse:
    type: object
    required:
    - msg
    - result
    - id
    properties:
      msg:
        type: string
      result:
        type: string
      id:
        type: integer
        format: int64

  # /events
  EventsResponse:
    type: object
    required:
    - msg
    - result
    - events
    properties:
      msg:
        type: string
      result:
        type: string
      events:
        type: array
        items:
          $ref: '#/definitions/event'

  #####
  # definitions used by /register
  #

  #alert_words
  #attachments
  #muted_topics
  #presences
  #realm_authentication_methods
  #realm_bots
  #realm_domains
  #realm_emoji
  #realm_filters
  #subscriptions
  #unsubscribed

  message:
    type: object
    required:
      - reactions
      - recipient_id
      - content_type
      - timestamp
      - display_recipient
      - sender_id
      - sender_full_name
      - client
      - content
      - stream_id
      - avatar_url
      - flags
      - sender_email
      - topic_links
      - sender_realm_str
      - subject
      - type
      - id
      - sender_short_name
    properties:
      reactions:
        # TODO: Create a full definition for reactions
        type: object
      recipient_id:
        type: integer
      content_type:
        type: string
      timestamp:
        type: integer
      display_recipient:
        type: array
        description: |
                     If the recipient is a stream, this will be a `string`
                     (not an `array`), with the stream's name.
        items:
          type: object
          # TODO: Create a definition for this type of user (doesn't match
          # the already existing ones)
      sender_id:
        type: integer
      sender_full_name:
        type: string
      client:
        type: string
      content:
        type: string
      stream_id:
        type: integer
      avatar_url:
        type: string
      flags:
        type: array
        items:
          type: string
      sender_email:
        type: string
      topic_links:
        type: array
        items:
          type: string
      sender_realm_str:
        type: string
      subject:
        type: string
      type:
        type: string
      id:
        type: integer
      sender_short_name:
        type: string

  stream:
    type: object
    required:
    - stream_id
    - description
    - name
    - invite_only
    properties:
      stream_id:
        type: integer
        format: int64
      description:
        type: string
      name:
        type: string
      invite_only:
        type: boolean

  user:
    type: object
    required:
    - is_admin
    - user_id
    - email
    - full_name
    - is_bot
    properties:
      is_admin:
        type: boolean
      user_id:
        type: integer
        format: int64
      email:
        type: string
      full_name:
        type: string
      is_bot:
        type: boolean

  #####
  # definitions used by /events
  #
  event:
    type: object
    required:
    - type
    - id
    properties:
      type:
        type: string
      id:
        type: integer
        format: int64