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
      produces:
        - application/json
      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'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

  /register:
    post:
      description: Register a queue to receive new messages
      operationId: registerQueue
      produces:
        - application/json
      parameters:
        - name: event_types
          in: formData
          description: |
                       (optional) 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: |
                       (Optional) 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'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

  /events:
    get:
      description: Get new events from an events queue
      operationId: getEvents
      produces:
        - application/json
      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: |
                       (Optional) 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'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

  /users/{user}/presence:
    get:
      description: Get presence data for another user.
      operationId: getPresence
      produces:
        - application/json
      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
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

  /user_uploads:
    post:
      description: Upload a file, and print the corresponding URI.
      operationId: userUploads
      consumes:
        - multipart/form-data
      produces:
        - application/json
      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
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

  /messages/{message_id}/:
    get:
      description: Retrieve the content of a message.
      produces:
        - application/json
      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.
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'
    patch:
      description: Edit a message that has already been sent.
      produces:
        - application/json
      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:
            type: object
            required:
              - msg
              - result
            properties:
              msg:
                type: string
              result:
                type: string
        '400':
          description: Bad request.
          schema:
            type: object
            required:
              - msg
              - result
            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
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorModel'

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

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

  # Unexpected error
  ErrorModel:
    type: object
    required:
      - msg
      - result
    properties:
      msg:
        type: string
      result:
        type: string