# 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 Threads List API version: 1.0.0 paths: "/rooms/{roomId}/threads": get: x-addedInMatrixVersion: "1.4" summary: Fetches a list of the threads in a room. description: |- This API is used to paginate through the list of the thread roots in a given room. Optionally, the returned list may be filtered according to whether the requesting user has participated in the thread. operationId: getThreadRoots security: - accessToken: [] parameters: - in: path name: roomId description: The room ID where the thread roots are located. required: true example: "!room:example.org" schema: type: string - in: query name: include description: |- Optional (default `all`) flag to denote which thread roots are of interest to the caller. When `all`, all thread roots found in the room are returned. When `participated`, only thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships) will be returned. example: all schema: type: string enum: - all - participated - in: query name: limit description: |- Optional limit for the maximum number of thread roots to include per response. Must be an integer greater than zero. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. example: 20 schema: type: integer - in: query name: from description: |- A pagination token from a previous result. When not provided, the server starts paginating from the most recent event visible to the user (as per history visibility rules; topologically). example: next_batch_token schema: type: string responses: "200": description: A portion of the available thread roots in the room, based on the filter criteria. content: application/json: schema: type: object properties: chunk: type: array description: |- The thread roots, ordered by the `latest_event` in each event's aggregated children. All events returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events). If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the event is returned redacted to the caller. This is to simulate the same behaviour of a client doing aggregation locally on the thread. items: $ref: definitions/client_event.yaml next_batch: type: string description: |- A token to supply to `from` to keep paginating the responses. Not present when there are no further results. required: - chunk examples: response: value: { "chunk": [ { "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" } ], "next_batch": "next_batch_token" } "400": description: |- The request was invalid in some way. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The `from` token is unknown to the server. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_INVALID_PARAM", "error": "Unknown pagination token" } "403": description: |- The user cannot view or peek on the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejection are: - The room is not set up for peeking. - The user has been banned from the room. - The room does not exist. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_FORBIDDEN", "error": "You are not allowed to view this room." } "429": description: This request was rate-limited. content: application/json: schema: $ref: definitions/errors/rate_limited.yaml tags: - Threads 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