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.
374 lines
14 KiB
YAML
374 lines
14 KiB
YAML
# Copyright 2022,2024 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 Relations API
|
|
version: 1.0.0
|
|
paths:
|
|
"/rooms/{roomId}/relations/{eventId}":
|
|
get:
|
|
summary: Get the child events for a given parent event.
|
|
description: |-
|
|
Retrieve all of the child events for a given parent event.
|
|
|
|
Note that when paginating the `from` token should be "after" the `to` token in
|
|
terms of topological ordering, because it is only possible to paginate "backwards"
|
|
through events, starting at `from`.
|
|
|
|
For example, passing a `from` token from page 2 of the results, and a `to` token
|
|
from page 1, would return the empty set. The caller can use a `from` token from
|
|
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
|
operationId: getRelatingEvents
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/roomId'
|
|
- $ref: '#/components/parameters/eventId'
|
|
- $ref: '#/components/parameters/from'
|
|
- $ref: '#/components/parameters/to'
|
|
- $ref: '#/components/parameters/limit'
|
|
- $ref: '#/components/parameters/dir'
|
|
- $ref: '#/components/parameters/recurse'
|
|
responses:
|
|
# note: this endpoint deliberately does not support rate limiting, therefore a
|
|
# 429 error response is not included.
|
|
"200":
|
|
description: |-
|
|
The paginated child events which point to the parent. If no events are
|
|
pointing to the parent or the pagination yields no results, an empty `chunk`
|
|
is returned.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/response'
|
|
- type: object
|
|
properties:
|
|
chunk:
|
|
title: ChildEventsChunk
|
|
type: array
|
|
description: The child events of the requested event, ordered topologically
|
|
most-recent first.
|
|
items:
|
|
$ref: definitions/client_event.yaml
|
|
required:
|
|
- chunk
|
|
examples:
|
|
response:
|
|
$ref: '#/components/examples/response'
|
|
"404":
|
|
$ref: '#/components/responses/404'
|
|
tags:
|
|
- Event relationships
|
|
# The same as above, with added `/{relType}`
|
|
"/rooms/{roomId}/relations/{eventId}/{relType}":
|
|
get:
|
|
summary: Get the child events for a given parent event, with a given `relType`.
|
|
description: |-
|
|
Retrieve all of the child events for a given parent event which relate to the parent
|
|
using the given `relType`.
|
|
|
|
Note that when paginating the `from` token should be "after" the `to` token in
|
|
terms of topological ordering, because it is only possible to paginate "backwards"
|
|
through events, starting at `from`.
|
|
|
|
For example, passing a `from` token from page 2 of the results, and a `to` token
|
|
from page 1, would return the empty set. The caller can use a `from` token from
|
|
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
|
operationId: getRelatingEventsWithRelType
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/roomId'
|
|
- $ref: '#/components/parameters/eventId'
|
|
- $ref: '#/components/parameters/relType'
|
|
- $ref: '#/components/parameters/from'
|
|
- $ref: '#/components/parameters/to'
|
|
- $ref: '#/components/parameters/limit'
|
|
- $ref: '#/components/parameters/dir'
|
|
- $ref: '#/components/parameters/recurse'
|
|
responses:
|
|
# note: this endpoint deliberately does not support rate limiting, therefore a
|
|
# 429 error response is not included.
|
|
"200":
|
|
description: |-
|
|
The paginated child events which point to the parent. If no events are
|
|
pointing to the parent or the pagination yields no results, an empty `chunk`
|
|
is returned.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/response'
|
|
- type: object
|
|
properties:
|
|
chunk:
|
|
title: ChildEventsChunk
|
|
type: array
|
|
description: |-
|
|
The child events of the requested event, ordered topologically
|
|
most-recent first. The events returned will match the `relType`
|
|
supplied in the URL.
|
|
items:
|
|
$ref: definitions/client_event.yaml
|
|
required:
|
|
- chunk
|
|
examples:
|
|
response:
|
|
$ref: '#/components/examples/response'
|
|
"404":
|
|
$ref: '#/components/responses/404'
|
|
tags:
|
|
- Event relationships
|
|
# The same as above, with added `/{eventType}`
|
|
"/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
|
|
get:
|
|
summary: Get the child events for a given parent event, with a given `relType`
|
|
and `eventType`.
|
|
description: |-
|
|
Retrieve all of the child events for a given parent event which relate to the parent
|
|
using the given `relType` and have the given `eventType`.
|
|
|
|
Note that when paginating the `from` token should be "after" the `to` token in
|
|
terms of topological ordering, because it is only possible to paginate "backwards"
|
|
through events, starting at `from`.
|
|
|
|
For example, passing a `from` token from page 2 of the results, and a `to` token
|
|
from page 1, would return the empty set. The caller can use a `from` token from
|
|
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
|
operationId: getRelatingEventsWithRelTypeAndEventType
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/roomId'
|
|
- $ref: '#/components/parameters/eventId'
|
|
- $ref: '#/components/parameters/relType'
|
|
- in: path
|
|
name: eventType
|
|
description: |-
|
|
The event type of child events to search for.
|
|
|
|
Note that in encrypted rooms this will typically always be `m.room.encrypted`
|
|
regardless of the event type contained within the encrypted payload.
|
|
required: true
|
|
example: m.room.message
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/from'
|
|
- $ref: '#/components/parameters/to'
|
|
- $ref: '#/components/parameters/limit'
|
|
- $ref: '#/components/parameters/dir'
|
|
- $ref: '#/components/parameters/recurse'
|
|
responses:
|
|
# note: this endpoint deliberately does not support rate limiting, therefore a
|
|
# 429 error response is not included.
|
|
"200":
|
|
description: |-
|
|
The paginated child events which point to the parent. If no events are
|
|
pointing to the parent or the pagination yields no results, an empty `chunk`
|
|
is returned.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/response'
|
|
- type: object
|
|
properties:
|
|
chunk:
|
|
title: ChildEventsChunk
|
|
type: array
|
|
description: |-
|
|
The child events of the requested event, ordered topologically most-recent
|
|
first. The events returned will match the `relType` and `eventType` supplied
|
|
in the URL.
|
|
items:
|
|
$ref: definitions/client_event.yaml
|
|
required:
|
|
- chunk
|
|
examples:
|
|
response:
|
|
$ref: '#/components/examples/response'
|
|
"404":
|
|
$ref: '#/components/responses/404'
|
|
tags:
|
|
- Event relationships
|
|
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
|
|
parameters:
|
|
roomId:
|
|
in: path
|
|
name: roomId
|
|
description: The ID of the room containing the parent event.
|
|
required: true
|
|
example: "!636q39766251:matrix.org"
|
|
schema:
|
|
type: string
|
|
eventId:
|
|
in: path
|
|
name: eventId
|
|
description: The ID of the parent event whose child events are to be returned.
|
|
required: true
|
|
example: $asfDuShaf7Gafaw
|
|
schema:
|
|
type: string
|
|
from:
|
|
in: query
|
|
name: from
|
|
description: |-
|
|
The pagination token to start returning results from. If not supplied, results
|
|
start at the most recent topological event known to the server.
|
|
|
|
Can be a `next_batch` or `prev_batch` token from a previous call, or a returned
|
|
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
|
|
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
|
|
required: false
|
|
example: page2_token
|
|
schema:
|
|
type: string
|
|
to:
|
|
in: query
|
|
name: to
|
|
description: |-
|
|
The pagination token to stop returning results at. If not supplied, results
|
|
continue up to `limit` or until there are no more events.
|
|
|
|
Like `from`, this can be a previous token from a prior call to this endpoint
|
|
or from `/messages` or `/sync`.
|
|
required: false
|
|
example: page3_token
|
|
schema:
|
|
type: string
|
|
limit:
|
|
in: query
|
|
name: limit
|
|
description: |-
|
|
The maximum number of results to return in a single `chunk`. The server can
|
|
and should apply a maximum value to this parameter to avoid large responses.
|
|
|
|
Similarly, the server should apply a default value when not supplied.
|
|
required: false
|
|
example: 20
|
|
schema:
|
|
type: integer
|
|
dir:
|
|
in: query
|
|
name: dir
|
|
x-addedInMatrixVersion: "1.4"
|
|
description: |-
|
|
Optional (default `b`) 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`.
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- b
|
|
- f
|
|
relType:
|
|
in: path
|
|
name: relType
|
|
description: The [relationship type](/client-server-api/#relationship-types) to
|
|
search for.
|
|
required: true
|
|
example: org.example.my_relation
|
|
schema:
|
|
type: string
|
|
recurse:
|
|
in: query
|
|
name: recurse
|
|
x-addedInMatrixVersion: "1.10"
|
|
required: false
|
|
description: |-
|
|
Whether to additionally include events which only relate indirectly to the
|
|
given event, i.e. events related to the given event via two or more direct relationships.
|
|
|
|
If set to `false`, only events which have direct a relation with the given
|
|
event will be included.
|
|
|
|
If set to `true`, all events which relate to the given event, or relate to
|
|
events that relate to the given event, will be included.
|
|
|
|
It is recommended that homeservers traverse at least 3 levels of relationships.
|
|
Implementations may perform more but should be careful to not infinitely recurse.
|
|
|
|
The default value is `false`.
|
|
schema:
|
|
type: boolean
|
|
schemas:
|
|
response:
|
|
type: object
|
|
properties:
|
|
next_batch:
|
|
type: string
|
|
description: |-
|
|
An opaque string representing a pagination token. The absence of this token
|
|
means there are no more results to fetch and the client should stop paginating.
|
|
prev_batch:
|
|
type: string
|
|
description: |-
|
|
An opaque string representing a pagination token. The absence of this token
|
|
means this is the start of the result set, i.e. this is the first batch/page.
|
|
recursion_depth:
|
|
type: integer
|
|
description: |-
|
|
If the `recurse` parameter was supplied by the client, this response field is
|
|
mandatory and gives the actual depth to which the server recursed. If the client
|
|
did not specify the `recurse` parameter, this field must be absent.
|
|
responses:
|
|
"404":
|
|
description: |-
|
|
The parent event was not found or the user does not have permission to read
|
|
this event (it might be contained in history that is not accessible to the user).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Event not found."
|
|
}
|
|
examples:
|
|
response:
|
|
value: {
|
|
"chunk": [
|
|
{
|
|
"room_id": "!636q39766251:matrix.org",
|
|
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
|
|
"content": {
|
|
"m.relates_to": {
|
|
"rel_type": "org.example.my_relation",
|
|
"event_id": "$asfDuShaf7Gafaw"
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"next_batch": "page2_token",
|
|
"prev_batch": "page1_token"
|
|
}
|