matrix-spec/data/api/client-server/threads_list.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 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