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

# Copyright 2022 The Matrix.org Foundation C.I.C.
#
# 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.
swagger: '2.0'
info:
  title: "Matrix Client-Server events in room by date API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/rooms/{roomId}/timestamp_to_event":
    get:
      x-addedInMatrixVersion: "1.6"
      summary: Get the closest event ID to the given timestamp
      description: |-
        Get the ID of the event closest to the given timestamp, in the
        direction specified by the `dir` parameter.

        If the server does not have all of the room history and does not have
        an event suitably close to the requested timestamp, it can use the
        corresponding [federation endpoint](/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)
        to ask other servers for a suitable event.

        After calling this endpoint, clients can call
        [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid)
        to obtain a pagination token to retrieve the events around the returned event.

        The event returned by this endpoint could be an event that the client
        cannot render, and so may need to paginate in order to locate an event
        that it can display, which may end up being outside of the client's
        suitable range.  Clients can employ different strategies to display
        something reasonable to the user.  For example, the client could try
        paginating in one direction for a while, while looking at the
        timestamps of the events that it is paginating through, and if it
        exceeds a certain difference from the target timestamp, it can try
        paginating in the opposite direction.  The client could also simply
        paginate in one direction and inform the user that the closest event
        found in that direction is outside of the expected range.
      operationId: getEventByTimestamp
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The ID of the room to search
          required: true
          x-example: "!636q39766251:matrix.org"
        - in: query
          type: integer
          name: ts
          description: |-
            The timestamp to search from, as given in milliseconds
            since the Unix epoch.
          required: true
          x-example: 1432684800000
        - in: query
          type: string
          enum: [f, b]
          name: dir
          description: |-
            The direction in which to search.  `f` for forwards, `b` for backwards.
          required: true
          x-example: f
      responses:
        200:
          description: |-
            An event was found matching the search parameters.
          schema:
            type: object
            properties:
              event_id:
                type: string
                description: |-
                  The ID of the event found
              origin_server_ts:
                type: integer
                description: |-
                  The event's timestamp, in milliseconds since the Unix epoch.
                  This makes it easy to do a quick comparison to see if the
                  `event_id` fetched is too far out of range to be useful for your
                  use case.
            required: ['event_id', 'origin_server_ts']
          examples:
            application/json: {
                "event_id": "$143273582443PhrSn:example.org",
                "origin_server_ts": 1432735824653
              }
        404:
          description: |-
            No event was found.
          examples:
            application/json: {
                "errcode": "M_NOT_FOUND",
                "error": "Unable to find event from 1432684800000 in forward direction"
              }
          schema:
            "$ref": "definitions/errors/error.yaml"
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - Room participation