matrix-spec/data/api/client-server/message_pagination.yaml

# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Client-Server Rooms API
  version: 1.0.0
paths:
  "/rooms/{roomId}/messages":
    get:
      summary: Get a list of events for this room
      description: |-
        This API returns a list of message and state events for a room. It uses
        pagination query parameters to paginate history in the room.

        *Note*: This endpoint supports lazy-loading of room member events. See
        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
      operationId: getRoomEvents
      security:
        - accessToken: []
      parameters:
        - in: path
          name: roomId
          description: The room to get events from.
          required: true
          example: "!636q39766251:example.com"
          schema:
            type: string
        - in: query
          name: from
          x-changedInMatrixVersion:
            "1.3": |
              Previously, this field was required and paginating from the first or
              last visible event in the room history wasn't supported.
          description: |-
            The token to start returning events from. This token can be obtained
            from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
            or from an `end` token returned by a previous request to this endpoint.

            This endpoint can also accept a value returned as a `start` token
            by a previous request to this endpoint, though servers are not
            required to support this. Clients should not rely on the behaviour.

            If it is not provided, the homeserver shall return a list of messages
            from the first or last (per the value of the `dir` parameter) visible
            event in the room history for the requesting user.
          required: false
          example: s345_678_333
          schema:
            type: string
        - in: query
          name: to
          description: |-
            The token to stop returning events at. This token can be obtained from
            a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
            or from an `end` token returned by a previous request to this endpoint.
          required: false
          schema:
            type: string
        - in: query
          name: dir
          description: |-
            The direction to return events from. If this is set to `f`, events
            will be returned in chronological order starting at `from`. If it
            is set to `b`, events will be returned in *reverse* chronological
            order, again starting at `from`.
          required: true
          example: b
          schema:
            type: string
            enum:
              - b
              - f
        - in: query
          name: limit
          description: "The maximum number of events to return. Default: 10."
          example: 3
          schema:
            type: integer
        - in: query
          name: filter
          description: A JSON RoomEventFilter to filter returned events with.
          example: '{"contains_url":true}'
          schema:
            type: string
      responses:
        "200":
          description: A list of messages with a new token to request more.
          content:
            application/json:
              schema:
                type: object
                description: A list of messages with a new token to request more.
                properties:
                  start:
                    type: string
                    description: |-
                      A token corresponding to the start of `chunk`. This will be the same as
                      the value given in `from`.
                  end:
                    type: string
                    description: |-
                      A token corresponding to the end of `chunk`. This token can be passed
                      back to this endpoint to request further events.

                      If no further events are available (either because we have
                      reached the start of the timeline, or because the user does
                      not have permission to see any more events), this property
                      is omitted from the response.
                  chunk:
                    type: array
                    description: |-
                      A list of room events. The order depends on the `dir` parameter.
                      For `dir=b` events will be in reverse-chronological order,
                      for `dir=f` in chronological order. (The exact definition of `chronological`
                      is dependent on the server implementation.)

                      Note that an empty `chunk` does not *necessarily* imply that no more events
                      are available. Clients should continue to paginate until no `end` property
                      is returned.
                    items:
                      $ref: definitions/client_event.yaml
                  state:
                    type: array
                    description: |-
                      A list of state events relevant to showing the `chunk`. For example, if
                      `lazy_load_members` is enabled in the filter then this may contain
                      the membership events for the senders of events in the `chunk`.

                      Unless `include_redundant_members` is `true`, the server
                      may remove membership events which would have already been
                      sent to the client in prior calls to this endpoint, assuming
                      the membership of those members has not changed.
                    items:
                      $ref: definitions/client_event.yaml
                required:
                  - start
                  - chunk
              examples:
                response:
                  value: {
                    "start": "t47429-4392820_219380_26003_2265",
                    "end": "t47409-4357353_219380_26003_2265",
                    "chunk": [
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                      },
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.name.yaml"
                      },
                      {
                        "room_id": "!636q39766251:example.com",
                        "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
                      }
                    ]
                  }
        "403":
          description: |
            You aren't a member of the room.
      tags:
        - Room participation
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    $ref: definitions/security.yaml