zulip/static/yaml/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

# 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:

  /messages:
    get:
      description: |
                   Retrieve a specific amount of messages, previous and
                   posterior to the specified `anchor`.
      operationId: zerver.views.messages.get_messages_backend
      parameters:
        - name: anchor
          in: query
          description: A message ID.
          required: true
          type: integer
        - name: num_before
          in: query
          description: The number of messages to retrieve before the anchor value.
          required: true
          type: integer
        - name: num_after
          in: query
          description: The number of messages to retrieve after the anchor value.
          required: true
          type: integer
      security:
        - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/MessagesResponse'

    post:
      description: Send a message
      operationId: zerver.views.messages.send_message_backend
      parameters:
      - name: type
        in: formData
        description: One of {`private`, `stream`}
        required: true
        type: string
      - name: content
        in: formData
        description: The content of the message. Maximum message size of 10000 bytes.
        required: true
        type: string
      - name: to
        in: formData
        description: |
                     In the case of a stream message, a string identifying the
                     stream. In the case of a private message, a JSON-encoded
                     list containing the usernames of the recipients.
        required: true
        type: string
      - name: subject
        in: formData
        description: |
                     The topic for the message (only required if type is `stream`).
                     Maximum length of 60 characters.
        required: false
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: |
                       * `msg`:

                       * `result`:

                       * `id`: The ID of the newly created message.
          schema:
            $ref: '#/definitions/MessageResponse'

  /register:
    post:
      description: Register a queue to receive new messages
      operationId: registerQueue
      parameters:
      - name: event_types
        in: formData
        description: |
                     A JSON-encoded array indicating which types of
                     events you're interested in. Values that you might find
                     useful include:

                     `message` (messages),

                     `subscriptions` (changes in your subscriptions),

                     `realm_user` (changes in the list of users in your realm), and

                     `pointer` (changes in your pointer).

                     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"]`

        required: false
        type: string
      - name: apply_markdown
        in: formData
        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.)
        required: false
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: |
                       ## These values will always be in the response:

                       * `msg`:

                       * `result`:

                       * `queue_id`: The ID of the queue that has been allocated for
                       your client.

                       * `last_event_id`: The initial value of the `last_event_id`
                       value to pass to `GET /api/v1/events`.

                       ## The following values may be returned, depending on the value
                       of `event_types` provided:

                       * `max_message_id`:

                       * `pointer`:

                       * `realm_users`:

                       * `alert_words`:

                       * `attachments`:

                       * `default_language`:

                       * `enable_desktop_notifications`:

                       * `enable_digest_emails`:

                       * `enable_offline_email_notifications`:

                       * `enable_offline_push_notifications`:

                       * `enable_online_push_notifications`:

                       * `enable_sounds`:

                       * `enable_stream_desktop_notifications`:

                       * `enable_stream_sounds`:

                       * `left_side_userlist`:

                       * `muted_topics`:

                       * `never_subscribed`:

                       * `presences`:

                       * `realm_add_emoji_by_admins_only`:

                       * `realm_allow_message_editing`:

                       * `realm_authentication_methods`:

                       * `realm_bots`:

                       * `realm_create_stream_by_admins_only`:

                       * `realm_default_language`:

                       * `realm_default_streams`:

                       * `realm_domain`:

                       * `realm_domains`:

                       * `realm_emoji`:

                       * `realm_filters`:

                       * `realm_invite_by_admins_only`:

                       * `realm_invite_required`:

                       * `realm_message_content_edit_limit_seconds`:

                       * `realm_name`:

                       * `realm_restricted_to_domain`:

                       * `realm_users`:

                       * `realm_waiting_period_threshold`:

                       * `referrals`:

                       * `streams`:

                       * `twenty_four_hour_time`:

                       * `unsubscribed`:

          schema:
            $ref: '#/definitions/RegisterResponse'

  /events:
    get:
      description: Get new events from an events queue
      operationId: getEvents
      parameters:
      - name: queue_id
        in: query
        description: The ID of a queue that you registered via `POST /api/v1/register`.
        required: true
        type: string
      - 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` in
                     the zulip Python module for an example implementation of
                     correctly processing each event exactly once.
        required: true
        type: string
      - 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.
        required: false
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: |
                       * `events`: An array (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.
          schema:
            $ref: '#/definitions/EventsResponse'

  /users/{user}/presence:
    get:
      description: Get presence data for another user.
      operationId: getPresence
      parameters:
      - name: user
        in: path
        description: Enter email address
        required: true
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: The response from a successful call
          schema:
            type: object
            required:
            - msg
            - result
            - presence
            properties:
              msg:
                type: string
              result:
                type: string
              presence:
                type: array
  /user_uploads:
    post:
      description: Upload a file, and print the corresponding URI.
      operationId: userUploads
      consumes:
      - multipart/form-data
      parameters:
      - name: file
        in: formData
        description: File to be uploaded
        type: file
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          schema:
            type: object
            required:
            - msg
            - result
            - uri
            properties:
              msg:
                type: string
              result:
                type: string
              uri:
                type: string

  /messages/{message_id}/:
    get:
      description: Retrieve the content of a message.
      parameters:
      - name: message_id
        in: path
        description: ID of the message to be retrieved.
        type: integer
        required: true
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success.
          schema:
            type: object
            required:
            - msg
            - result
            - raw_content
            properties:
              msg:
                type: string
              result:
                type: string
              raw_content:
                type: string
                description: Body of the queried message.
    patch:
      description: Edit a message that has already been sent.
      parameters:
      - name: message_id
        in: path
        description: ID of the message to be edited.
        type: integer
        required: true
      - name: subject
        in: query
        description: Message's new topic.
        type: string
      - 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.
        type: string
        enum:
          - change_one
          - change_later
          - change_all
        default: "change_one"
      - name: content
        in: query
        description: Message's new body.
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/JsonSuccess'
        '400':
          description: Bad request.
          schema:
            allOf:
            - $ref: '#/definitions/JsonError'
            - properties:
                msg:
                  type: string
                  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

  /streams:
    get:
      description: Gets a list of streams available to a user on the server.
      operationId: zerver.views.streams.get_streams_backend
      security:
      - basicAuth: []
      parameters:
      - name: include_public
        in: query
        description: |
                     Set to `false` if the response should not include
                     public streams.
        type: string
        default: true
      - name: include_all_active
        in: query
        description: |
                     Set to `true` if the response should include all active
                     streams, including private ones. This requires
                     API super user access.
        type: string
        default: false
      - name: include_default
        in: query
        description: |
                     Set to `true` if the response should include all the
                     streams to which new users are subscribed by default.
        type: string
        default: false
      - name: include_subscribed
        in: query
        description: |
                     Set to `false` if response should not include streams
                     where user is considered subscribed.
        type: string
        default: true
      responses:
        '200':
          description: Success.
          schema:
            allOf:
            - $ref: '#/definitions/JsonSuccess'
            - description: |
                           `stream` is an array (that can be zero-length
                           depending on the parameters set) of available
                           streams for the authenticated user.
            - properties:
                streams:
                  type: array
                  items:
                    $ref: '#/definitions/stream'

#######################
# 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:
        msg:
          type: string
          default: success

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

  # /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_sounds:
        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_editing:
        type: boolean
      realm_authentication_methods:
        type: string
      realm_bots:
        type: string
      realm_create_stream_by_admins_only:
        type: boolean
      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_name:
        type: string
      realm_restricted_to_domain:
        type: boolean
      realm_users:
        type: array
        items:
          $ref: "#/definitions/user"
      realm_waiting_period_threshold:
        type: integer
        format: int64
      referrals:
        type: string
      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
  #referrals
  #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
      - subject_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
      subject_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