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:
    post:
      description: Send a message
      operationId: addMessage
      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 topic.
        type: string
      - name: propagate_mode
        in: query
        description: propagation mode
        type: string
        default: "change_one"
      - name: content
        in: query
        description: Message's body.
        type: string
      security:
      - basicAuth: []
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/JsonSuccess'
        '400':
          description: Bad request.
          schema:
            $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
              result:
                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
    required:
    - msg
    - result
    properties:
      msg:
        type: string
      result:
        type: string

  JsonSuccess:
    allOf:
    - $ref: '#/definitions/JsonResponse'
      properties:
        msg:
          default: success

  JsonError:
    allOf:
    - $ref: '#/definitions/JsonResponse'
      properties:
        msg:
          default: error

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

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

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

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

  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

  # /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 /events
  #
  event:
    type: object
    required:
    - type
    - id
    properties:
      type:
        type: string
      id:
        type: integer
        format: int64