openapi: 3.0.1
info:
  version: 1.0.0
  title: Zulip REST authentication scheduled_messages API
  description: 'Powerful open source group chat

    '
  contact:
    url: https://zulip.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
  variables:
    subdomain:
      default: example
- url: '{server}/api/v1'
  variables:
    server:
      default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: scheduled_messages
paths:
  /scheduled_messages:
    get:
      operationId: get-scheduled-messages
      tags:
      - scheduled_messages
      summary: Get scheduled messages
      description: 'Fetch all [scheduled messages](/help/schedule-a-message) for

        the current user.


        Scheduled messages are messages the user has scheduled to be

        sent in the future via the send later feature.


        **Changes**: New in Zulip 7.0 (feature level 173).

        '
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                    ignored_parameters_unsupported: {}
                    scheduled_messages:
                      type: array
                      description: 'Returns all of the current user''s undelivered scheduled

                        messages, ordered by `scheduled_delivery_timestamp`

                        (ascending).

                        '
                      items:
                        $ref: '#/components/schemas/ScheduledMessage'
                  example:
                    result: success
                    msg: ''
                    scheduled_messages:
                    - scheduled_message_id: 27
                      to: 14
                      type: stream
                      content: Hi
                      rendered_content: <p>Hi</p>
                      topic: Introduction
                      scheduled_delivery_timestamp: 1681662420
                      failed: false
    post:
      operationId: create-scheduled-message
      tags:
      - scheduled_messages
      summary: Create a scheduled message
      description: 'Create a new [scheduled message](/help/schedule-a-message).


        **Changes**: In Zulip 7.0 (feature level 184), moved support for

        [editing a scheduled message](/api/update-scheduled-message) to a

        separate API endpoint, which removed the `scheduled_message_id`

        parameter from this endpoint.


        New in Zulip 7.0 (feature level 179).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                type:
                  description: 'The type of scheduled message to be sent. `"direct"` for a direct

                    message and `"stream"` or `"channel"` for a channel message.


                    Note that, while `"private"` is supported for scheduling direct

                    messages, clients are encouraged to use to the modern convention of

                    `"direct"` to indicate this message type, because support for

                    `"private"` may eventually be removed.


                    **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as

                    an additional value for this parameter to indicate the type of a channel

                    message.

                    '
                  type: string
                  enum:
                  - direct
                  - channel
                  - stream
                  - private
                  example: direct
                to:
                  description: 'The scheduled message''s tentative target audience.


                    For channel messages, the integer ID of the channel.

                    For direct messages, a list containing integer user IDs.

                    '
                  oneOf:
                  - type: integer
                  - type: array
                    items:
                      type: integer
                    minLength: 1
                  example:
                  - 9
                  - 10
                content:
                  $ref: '#/components/schemas/RequiredContent'
                topic:
                  description: 'The topic of the message. Only required for channel messages

                    (`"type": "stream"` or `"type": "channel"`), ignored otherwise.


                    Clients should use the `max_topic_length` returned by the

                    [`POST /register`](/api/register-queue) endpoint to determine

                    the maximum topic length.


                    Note: When `"(no topic)"` or the value of `realm_empty_topic_display_name`

                    found in the [POST /register](/api/register-queue) response is used for this

                    parameter, it is interpreted as an empty string.


                    When [topics are required](/help/require-topics), this parameter can''t

                    be `"(no topic)"`, an empty string, or the value of `realm_empty_topic_display_name`.


                    **Changes**: Before Zulip 10.0 (feature level 370), `"(no topic)"`

                    was not interpreted as an empty string.


                    Before Zulip 10.0 (feature level 334), empty string

                    was not a valid topic name for channel messages.

                    '
                  type: string
                  example: Castle
                scheduled_delivery_timestamp:
                  type: integer
                  description: 'The UNIX timestamp for when the message will be sent,

                    in UTC seconds.

                    '
                  example: 3165826990
                read_by_sender:
                  type: boolean
                  description: 'Whether the message should be initially marked read by its

                    sender. If unspecified, the server uses a heuristic based

                    on the client name and the recipient.


                    **Changes**: New in Zulip 8.0 (feature level 236).

                    '
                  example: true
              required:
              - type
              - to
              - content
              - scheduled_delivery_timestamp
            encoding:
              to:
                contentType: application/json
              scheduled_delivery_timestamp:
                contentType: application/json
              read_by_sender:
                contentType: application/json
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                    ignored_parameters_unsupported: {}
                    scheduled_message_id:
                      type: integer
                      description: 'The unique ID of the scheduled message.


                        This is different from the unique ID that the message will have

                        after it is sent.

                        '
                  example:
                    msg: ''
                    scheduled_message_id: 42
                    result: success
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/components/schemas/NonExistingChannelIdError'
                  - description: 'A typical failed JSON response for when a channel message is scheduled

                      to be sent to a channel that does not exist:

                      '
                - allOf:
                  - $ref: '#/components/schemas/CodedError'
                  - example:
                      code: BAD_REQUEST
                      msg: Invalid user ID 10
                      result: error
                    description: 'A typical failed JSON response for when a direct message is scheduled

                      to be sent to a user that does not exist:

                      '
  /scheduled_messages/{scheduled_message_id}:
    patch:
      operationId: update-scheduled-message
      tags:
      - scheduled_messages
      summary: Edit a scheduled message
      description: 'Edit an existing [scheduled message](/help/schedule-a-message).


        **Changes**: New in Zulip 7.0 (feature level 184).

        '
      parameters:
      - name: scheduled_message_id
        in: path
        schema:
          type: integer
        description: 'The ID of the scheduled message to update.


          This is different from the unique ID that the message would have

          after being sent.

          '
        required: true
        example: 2
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                type:
                  description: 'The type of scheduled message to be sent. `"direct"` for a direct

                    message and `"stream"` or `"channel"` for a channel message.


                    When updating the type of the scheduled message, the `to` parameter

                    is required. And, if updating the type of the scheduled message to

                    `"stream"`/`"channel"`, then the `topic` parameter is also required.


                    Note that, while `"private"` is supported for scheduling direct

                    messages, clients are encouraged to use to the modern convention of

                    `"direct"` to indicate this message type, because support for

                    `"private"` may eventually be removed.


                    **Changes**: In Zulip 9.0 (feature level 248), `"channel"` was added as

                    an additional value for this parameter to indicate the type of a channel

                    message.

                    '
                  type: string
                  enum:
                  - direct
                  - channel
                  - stream
                  - private
                  example: stream
                to:
                  description: 'The scheduled message''s tentative target audience.


                    For channel messages, the integer ID of the channel.

                    For direct messages, a list containing integer user IDs.


                    Required when updating the `type` of the scheduled message.

                    '
                  oneOf:
                  - type: integer
                  - type: array
                    items:
                      type: integer
                    minLength: 1
                  example: 11
                content:
                  description: 'The updated content of the scheduled message.


                    Clients should use the `max_message_length` returned by the

                    [`POST /register`](/api/register-queue) endpoint to determine

                    the maximum message size.

                    '
                  type: string
                  example: Hello
                topic:
                  description: 'The updated topic of the scheduled message.


                    Required when updating the `type` of the scheduled message to

                    `"stream"` or `"channel"`. Ignored when the existing or updated

                    `type` of the scheduled message is `"direct"` (or `"private"`).


                    Clients should use the `max_topic_length` returned by the

                    [`POST /register`](/api/register-queue) endpoint to determine

                    the maximum topic length.


                    Note: When `"(no topic)"` or the value of `realm_empty_topic_display_name`

                    found in the [POST /register](/api/register-queue) response is used for this

                    parameter, it is interpreted as an empty string.


                    When [topics are required](/help/require-topics), this parameter can''t

                    be `"(no topic)"`, an empty string, or the value of `realm_empty_topic_display_name`.


                    **Changes**: Before Zulip 10.0 (feature level 370), `"(no topic)"`

                    was not interpreted as an empty string.


                    Before Zulip 10.0 (feature level 334), empty string

                    was not a valid topic name for channel messages.

                    '
                  type: string
                  example: Castle
                scheduled_delivery_timestamp:
                  type: integer
                  description: 'The UNIX timestamp for when the message will be sent,

                    in UTC seconds.


                    Required when updating a scheduled message that the server

                    has already tried and failed to send. This state is indicated

                    with `"failed": true` in `scheduled_messages` objects; see

                    response description at

                    [`GET /scheduled_messages`](/api/get-scheduled-messages#response).

                    '
                  example: 3165826990
            encoding:
              to:
                contentType: application/json
              scheduled_delivery_timestamp:
                contentType: application/json
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                    ignored_parameters_unsupported: {}
                  example:
                    result: success
                    msg: ''
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/components/schemas/NonExistingChannelIdError'
                  - description: 'A typical failed JSON response for when a channel message is scheduled

                      to be sent to a channel that does not exist:

                      '
                - allOf:
                  - $ref: '#/components/schemas/CodedError'
                  - example:
                      code: BAD_REQUEST
                      msg: Invalid user ID 10
                      result: error
                    description: 'A typical failed JSON response for when a direct message is scheduled

                      to be sent to a user that does not exist:

                      '
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - description: 'A typical failed JSON response for when no scheduled message exists

                    with the provided ID:

                    '
                  example:
                    code: BAD_REQUEST
                    result: error
                    msg: Scheduled message does not exist
    delete:
      operationId: delete-scheduled-message
      tags:
      - scheduled_messages
      summary: Delete a scheduled message
      description: 'Delete, and therefore cancel sending, a previously [scheduled

        message](/help/schedule-a-message).


        **Changes**: New in Zulip 7.0 (feature level 173).

        '
      parameters:
      - name: scheduled_message_id
        in: path
        schema:
          type: integer
        description: 'The ID of the scheduled message to delete.


          This is different from the unique ID that the message would have

          after being sent.

          '
        required: true
        example: 1
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - description: 'A typical failed JSON response for when no scheduled message exists

                    with the provided ID:

                    '
                  example:
                    code: BAD_REQUEST
                    result: error
                    msg: Scheduled message does not exist
components:
  schemas:
    JsonSuccessBase:
      description: '**Changes**: As of Zulip 7.0 (feature level 167), if any

        parameters sent in the request are not supported by this

        endpoint, a successful JSON response will include an

        [`ignored_parameters_unsupported`][ignored_params] array.


        A typical successful JSON response may look like:


        [ignored_params]: /api/rest-error-handling#ignored-parameters

        '
      allOf:
      - $ref: '#/components/schemas/JsonResponseBase'
      - required:
        - result
        - msg
        properties:
          result:
            enum:
            - success
          msg:
            type: string
          ignored_parameters_unsupported:
            $ref: '#/components/schemas/IgnoredParametersUnsupported'
    NonExistingChannelIdError:
      allOf:
      - $ref: '#/components/schemas/CodedErrorBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          code: {}
          stream_id:
            type: integer
            description: 'The channel ID that could not be found.

              '
        example:
          code: STREAM_DOES_NOT_EXIST
          msg: Channel with ID '9' does not exist
          result: error
          stream_id: 9
    RequiredContent:
      description: 'The content of the message.


        Clients should use the `max_message_length` returned by the

        [`POST /register`](/api/register-queue) endpoint to determine

        the maximum message size.

        '
      type: string
      example: Hello
    JsonSuccess:
      allOf:
      - $ref: '#/components/schemas/JsonSuccessBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          ignored_parameters_unsupported: {}
        example:
          msg: ''
          result: success
    ScheduledMessageBase:
      type: object
      description: 'Object containing details of the scheduled message.

        '
      properties:
        scheduled_message_id:
          type: integer
          description: 'The unique ID of the scheduled message, which can be used to

            modify or delete the scheduled message.


            This is different from the unique ID that the message will have

            after it is sent.

            '
        type:
          type: string
          description: 'The type of the scheduled message. Either `"stream"` or `"private"`.

            '
          enum:
          - stream
          - private
        to:
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
          description: 'The scheduled message''s tentative target audience.


            For channel messages, it will be the unique ID of the target

            channel. For direct messages, it will be an array with the

            target users'' IDs.

            '
        topic:
          type: string
          description: 'Only present if `type` is `"stream"`.


            The topic for the channel message.

            '
        content:
          type: string
          description: 'The content/body of the scheduled message, in [Zulip-flavored Markdown](/help/format-your-message-using-markdown) format.


            See [Markdown message formatting](/api/message-formatting) for details on Zulip''s HTML format.

            '
        rendered_content:
          type: string
          description: 'The content/body of the scheduled message rendered in HTML.

            '
        scheduled_delivery_timestamp:
          type: integer
          description: 'The UNIX timestamp for when the message will be sent

            by the server, in UTC seconds.

            '
          example: 1595479019
        failed:
          type: boolean
          description: 'Whether the server has tried to send the scheduled message

            and it failed to successfully send.


            Clients that support unscheduling and editing scheduled messages

            should display scheduled messages with `"failed": true` with an

            indicator that the server failed to send the message at the

            scheduled time, so that the user is aware of the failure and can

            get the content of the scheduled message.


            **Changes**: New in Zulip 7.0 (feature level 181).

            '
      additionalProperties: false
      required:
      - scheduled_message_id
      - type
      - to
      - content
      - rendered_content
      - scheduled_delivery_timestamp
      - failed
    IgnoredParametersUnsupported:
      type: array
      items:
        type: string
      description: 'An array of any parameters sent in the request that are not

        supported by the endpoint.


        See [error handling](/api/rest-error-handling#ignored-parameters) documentation

        for details on this and its change history.

        '
    JsonResponseBase:
      type: object
      properties:
        result:
          type: string
    ScheduledMessage:
      allOf:
      - $ref: '#/components/schemas/ScheduledMessageBase'
      - additionalProperties: false
        properties:
          scheduled_message_id: {}
          type: {}
          to: {}
          topic: {}
          content: {}
          rendered_content: {}
          scheduled_delivery_timestamp: {}
          failed: {}
    CodedError:
      allOf:
      - $ref: '#/components/schemas/CodedErrorBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          code: {}
    CodedErrorBase:
      allOf:
      - $ref: '#/components/schemas/JsonResponseBase'
      - required:
        - result
        - msg
        - code
        properties:
          result:
            enum:
            - error
          msg:
            type: string
          code:
            type: string
            description: 'A string that identifies the error.

              '
  responses:
    SimpleSuccess:
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'
  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.

        '