diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0e7e8473a..b20f1316f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2156,6 +2156,19 @@ following endpoint. This endpoint is particularly useful if the client has lost context on the aggregation for a parent event and needs to rebuild/verify it. +When using the `recurse` parameter, note that there no way for a client to +affect how much the server recurses. If the client decides that the server's +recursion level is insufficient, it could, for example, perform the recursion +manually, or disable whatever feature requires more recursion. + +Filters specified via `event_type` or `rel_type` will be applied to all events +returned, whether direct or indirect relations. Events that would match the filter, +but whose only relation to the original given event is through a non-matching +intermediate event, will not be included. This means that supplying a `rel_type` +parameter of `m.thread` is not appropriate for fetching all events in a thread since +relations to the threaded events would be filtered out. For this purpose, clients should +omit the `rel_type` parameter and perform any necessary filtering on the client side. + {{% boxes/note %}} Because replies do not use `rel_type`, they will not be accessible via this API. {{% /boxes/note %}} diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 65c3491ad..9002130e6 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -1,4 +1,4 @@ -# Copyright 2022 The Matrix.org Foundation C.I.C. +# 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. @@ -96,6 +96,26 @@ paths: enum: - b - f + - in: query + name: recurse + x-addedInMatrixVersion: "1.10" + required: false + description: |- + Whether to additionally include events which only relate indirectly to the + given event, ie. events related to the root events via one 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 at least 3 levels of relationships are traversed. + Implementations may perform more but should be careful to not infinitely recurse. + + The default value is `false`. + schema: + type: boolean responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -127,6 +147,12 @@ paths: 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. The the client + did not specify the `recurse` parameter, this field must be absent. required: - chunk examples: @@ -253,6 +279,24 @@ paths: enum: - b - f + - in: query + name: recurse + x-addedInMatrixVersion: "1.10" + required: false + description: |- + Whether to additionally include events which only relate indirectly to the + given event, ie. events related to the root events via one 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 at least 3 levels of relationships are traversed. + Implementations may perform more but should be careful to not infinitely recurse. + + The default value is `false`. responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -286,6 +330,12 @@ paths: 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. The the client + did not specify the `recurse` parameter, this field must be absent. required: - chunk examples: @@ -424,6 +474,24 @@ paths: enum: - b - f + - in: query + name: recurse + x-addedInMatrixVersion: "1.10" + required: false + description: |- + Whether to additionally include events which only relate indirectly to the + given event, ie. events related to the root events via one 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 at least 3 levels of relationships are traversed. + Implementations may perform more but should be careful to not infinitely recurse. + + The default value is `false`. responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -457,6 +525,12 @@ paths: 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. The the client + did not specify the `recurse` parameter, this field must be absent. required: - chunk examples: