# 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.
openapi: 3.1.0
info:
  title: Matrix Client-Server events in room by date API
  version: 1.0.0
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
          name: roomId
          description: The ID of the room to search
          required: true
          example: "!636q39766251:matrix.org"
          schema:
            type: string
        - in: query
          name: ts
          description: |-
            The timestamp to search from, as given in milliseconds
            since the Unix epoch.
          required: true
          example: 1432684800000
          schema:
            type: integer
        - in: query
          name: dir
          description: The direction in which to search.  `f` for forwards, `b` for
            backwards.
          required: true
          example: f
          schema:
            type: string
            enum:
              - f
              - b
      responses:
        "200":
          description: An event was found matching the search parameters.
          content:
            application/json:
              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:
                response:
                  value: {
                    "event_id": "$143273582443PhrSn:example.org",
                    "origin_server_ts": 1432735824653
                  }
        "404":
          description: No event was found.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_NOT_FOUND",
                    "error": "Unable to find event from 1432684800000 in forward direction"
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Room participation
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v1
components:
  securitySchemes:
    $ref: definitions/security.yaml