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/threads_list.yaml

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