# Copyright 2016 OpenMarket Ltd # # 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. swagger: '2.0' info: title: "Matrix Client-Server Room Directory API" version: "1.0.0" host: localhost:8008 schemes: - https - http basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: - application/json paths: "/directory/list/room/{roomId}": get: summary: Gets the visibility of a room in the directory description: |- Gets the visibility of a given room on the server's public room directory. operationId: getRoomVisibilityOnDirectory parameters: - in: path type: string name: roomId description: The room ID. required: true x-example: "!curbf:matrix.org" responses: 200: description: The visibility of the room in the directory schema: type: object properties: visibility: type: string enum: ['private', 'public'] description: The visibility of the room in the directory. examples: application/json: { "visibility": "public" } 404: description: The room is not known to the server examples: application/json: { "errcode": "M_NOT_FOUND", "error": "Room not found" } schema: "$ref": "definitions/errors/error.yaml" put: summary: Sets the visibility of a room in the room directory description: |- Sets the visibility of a given room in the server's public room directory. Servers may choose to implement additional access control checks here, for instance that room visibility can only be changed by the room creator or a server administrator. operationId: setRoomVisibilityOnDirectory security: - accessToken: [] parameters: - in: path type: string name: roomId description: The room ID. required: true x-example: "!curbf:matrix.org" - in: body name: body required: true description: |- The new visibility for the room on the room directory. schema: type: object properties: visibility: type: string enum: ["private", "public"] description: |- The new visibility setting for the room. Defaults to 'public'. example: { "visibility": "public" } responses: 200: description: The visibility was updated, or no change was needed. examples: application/json: {} 404: description: The room is not known to the server examples: application/json: { "errcode": "M_NOT_FOUND", "error": "Room not found" } schema: "$ref": "definitions/errors/error.yaml" "/publicRooms": get: summary: Lists the public rooms on the server. description: |- Lists the public rooms on the server. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first. operationId: getPublicRooms parameters: - in: query name: limit type: integer description: |- Limit the number of results returned. - in: query name: since type: string description: |- A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. - in: query name: server type: string description: |- The server to fetch the public room lists from. Defaults to the local server. responses: 200: description: A list of the rooms on the server. schema: $ref: "definitions/public_rooms_response.yaml" tags: - Room discovery post: summary: Lists the public rooms on the server with optional filter. description: |- Lists the public rooms on the server, with optional filter. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first. operationId: queryPublicRooms security: - accessToken: [] parameters: - in: query name: server type: string description: |- The server to fetch the public room lists from. Defaults to the local server. - in: body name: body required: true description: |- Options for which rooms to return. schema: type: object properties: limit: type: integer description: |- Limit the number of results returned. since: type: string description: |- A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag. filter: type: object title: "Filter" description: |- Filter to apply to the results. properties: generic_search_term: type: string description: |- A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). include_all_networks: type: boolean description: |- Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false. example: false third_party_instance_id: type: string description: |- The specific third party network/protocol to request from the homeserver. Can only be used if ``include_all_networks`` is false. example: "irc" example: { "limit": 10, "filter": { "generic_search_term": "foo" }, "include_all_networks": false, "third_party_instance_id": "irc" } responses: 200: description: A list of the rooms on the server. schema: type: object description: A list of the rooms on the server. required: ["chunk"] properties: chunk: title: "PublicRoomsChunks" type: array description: |- A paginated chunk of public rooms. items: type: object title: "PublicRoomsChunk" required: - room_id - num_joined_members - world_readable - guest_can_join properties: aliases: type: array description: |- Aliases of the room. May be empty. items: type: string canonical_alias: type: string description: |- The canonical alias of the room, if any. name: type: string description: |- The name of the room, if any. num_joined_members: type: integer description: |- The number of members joined to the room. room_id: type: string description: |- The ID of the room. topic: type: string description: |- The topic of the room, if any. world_readable: type: boolean description: |- Whether the room may be viewed by guest users without joining. guest_can_join: type: boolean description: |- Whether guest users may join the room and participate in it. If they can, they will be subject to ordinary power level rules like any other user. avatar_url: type: string description: The URL for the room's avatar, if one is set. next_batch: type: string description: |- A pagination token for the response. The absence of this token means there are no more results to fetch and the client should stop paginating. prev_batch: type: string description: |- A pagination token that allows fetching previous results. The absence of this token means there are no results before this batch, i.e. this is the first batch. total_room_count_estimate: type: integer description: |- An estimate on the total number of public rooms, if the server has an estimate. examples: application/json: { "chunk": [ { "aliases": ["#murrays:cheese.bar"], "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE", "guest_can_join": false, "name": "CHEESE", "num_joined_members": 37, "room_id": "!ol19s:bleecker.street", "topic": "Tasty tasty cheese", "world_readable": true } ], "next_batch": "p190q", "prev_batch": "p1902", "total_room_count_estimate": 115 } tags: - Room discovery