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.
139 lines
4.8 KiB
YAML
139 lines
4.8 KiB
YAML
# Copyright 2025 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 Room Summary API
|
|
version: 1.0.0
|
|
paths:
|
|
"/room_summary/{roomIdOrAlias}":
|
|
get:
|
|
x-addedInMatrixVersion: "1.15"
|
|
summary: Retrieves a summary for a room.
|
|
description: |-
|
|
Retrieves a summary for a room.
|
|
|
|
Clients should note that requests for rooms where the user's membership
|
|
is `invite` or `knock` might yield outdated, partial or even no data
|
|
since the server may not have access to the current state of the room.
|
|
|
|
Servers MAY allow unauthenticated access to this API if at least one of
|
|
the following conditions holds true:
|
|
|
|
- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
|
|
`knock_restricted`.
|
|
- The room has a `world_readable` [history visibility](#room-history-visibility).
|
|
|
|
Servers should consider rate limiting requests that require a federation
|
|
request more heavily if the client is unauthenticated.
|
|
operationId: getRoomSummary
|
|
security:
|
|
- signedRequest: []
|
|
parameters:
|
|
- in: path
|
|
name: roomIdOrAlias
|
|
description: The room identifier or alias to summarise.
|
|
required: true
|
|
example: "#monkeys:matrix.org"
|
|
schema:
|
|
oneOf:
|
|
- type: string
|
|
format: mx-room-id
|
|
pattern: "^!"
|
|
- type: string
|
|
format: mx-room-alias
|
|
pattern: "^#"
|
|
- in: query
|
|
name: via
|
|
description: |-
|
|
The servers to attempt to request the summary from when
|
|
the local server cannot generate it (for instance, because
|
|
it has no local user in the room).
|
|
example:
|
|
- matrix.org
|
|
- elsewhere.ca
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: mx-server-name
|
|
responses:
|
|
"200":
|
|
description: A summary of the room.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: A summary of the room.
|
|
allOf:
|
|
- $ref: ../client-server/definitions/room_summary.yaml
|
|
- type: object
|
|
properties:
|
|
membership:
|
|
description: |-
|
|
The membership state of the user if the user is joined to the room. Absent
|
|
if the API was called unauthenticated.
|
|
enum:
|
|
- invite
|
|
- join
|
|
- knock
|
|
- leave
|
|
- ban
|
|
type: string
|
|
examples:
|
|
response:
|
|
value: {
|
|
room_id: "!ol19s:bleecker.street",
|
|
avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
|
|
guest_can_join: false,
|
|
name: "CHEESE",
|
|
num_joined_members: 37,
|
|
topic: "Tasty tasty cheese",
|
|
world_readable: true,
|
|
join_rule: "public",
|
|
room_type: "m.space",
|
|
membership: "invite",
|
|
encryption: "m.megolm.v1.aes-sha2",
|
|
room_version: "9001",
|
|
}
|
|
"404":
|
|
description: |-
|
|
The room could not be found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ../client-server/definitions/errors/error.yaml
|
|
examples:
|
|
response:
|
|
value: {
|
|
"errcode": "M_NOT_FOUND",
|
|
"error": "Room not found."
|
|
}
|
|
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
|