# Copyright 2021 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 Space Hierarchy API version: 1.0.0 paths: "/rooms/{roomId}/hierarchy": get: x-addedInMatrixVersion: "1.2" summary: Retrieve a portion of a space tree. description: |- Paginates over the space tree in a depth-first manner to locate child rooms of a given space. Where a child room is unknown to the local server, federation is used to fill in the details. The servers listed in the `via` array should be contacted to attempt to fill in missing rooms. Only [`m.space.child`](#mspacechild) state events of the room are considered. Invalid child rooms and parent events are not covered by this endpoint. operationId: getSpaceHierarchy security: - accessToken: [] parameters: - in: path name: roomId description: The room ID of the space to get a hierarchy for. required: true example: "!space:example.org" schema: type: string - in: query name: suggested_only description: |- Optional (default `false`) flag to indicate whether or not the server should only consider suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event contents. example: true schema: type: boolean - in: query name: limit description: |- Optional limit for the maximum number of rooms 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: max_depth description: |- Optional limit for how far to go into the space. Must be a non-negative integer. When reached, no further child rooms will be returned. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. example: 5 schema: type: integer - in: query name: from description: |- A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot be changed from the first request. example: next_batch_token schema: type: string responses: "200": description: A portion of the space tree, starting at the provided room ID. content: application/json: schema: type: object properties: rooms: type: array description: The rooms for the current page, with the current filters. items: allOf: - $ref: definitions/public_rooms_chunk.yaml - type: object title: ChildRoomsChunk properties: room_type: type: string description: The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any. children_state: type: array description: |- The [`m.space.child`](#mspacechild) events of the space-room, represented as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. If the room is not a space-room, this should be empty. items: allOf: - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml - type: object title: StrippedChildStateEvent properties: origin_server_ts: type: integer format: int64 description: The `origin_server_ts` for the event. required: - origin_server_ts required: - children_state 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: - rooms examples: response: value: { "rooms": [ { "room_id": "!space:example.org", "avatar_url": "mxc://example.org/abcdef", "guest_can_join": false, "name": "The First Space", "topic": "No other spaces were created first, ever", "world_readable": true, "join_rule": "public", "room_type": "m.space", "num_joined_members": 42, "canonical_alias": "#general:example.org", "children_state": [ { "type": "m.space.child", "state_key": "!a:example.org", "content": { "via": [ "example.org" ] }, "sender": "@alice:example.org", "origin_server_ts": 1629413349153 } ] } ], "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. - `suggested_only` or `max_depth` changed during pagination. content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_INVALID_PARAM", "error": "suggested_only and max_depth cannot change on paginated requests" } "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: - Spaces 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