You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/room_event_by_timestamp.yaml

144 lines
5.3 KiB
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.
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:
- accessTokenQuery: []
- accessTokenBearer: []
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:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer