# 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. openapi: 3.1.0 info: title: Matrix Client-Server Room Directory API version: 1.0.0 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 name: roomId description: The room ID. required: true example: "!curbf:matrix.org" schema: type: string responses: "200": description: The visibility of the room in the directory content: application/json: schema: type: object properties: visibility: type: string enum: - private - public description: The visibility of the room in the directory. examples: response: value: { "visibility": "public" } "404": description: The room is not known to the server content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "Room not found" } tags: - Room discovery 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 name: roomId description: The room ID. required: true example: "!curbf:matrix.org" schema: type: string requestBody: content: application/json: schema: type: object properties: visibility: type: string enum: - private - public description: |- The new visibility setting for the room. Defaults to 'public'. example: { "visibility": "public" } description: The new visibility for the room on the room directory. required: true responses: "200": description: The visibility was updated, or no change was needed. content: application/json: schema: type: object examples: response: value: {} "404": description: The room is not known to the server content: application/json: schema: $ref: definitions/errors/error.yaml examples: response: value: { "errcode": "M_NOT_FOUND", "error": "Room not found" } tags: - Room discovery /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 description: Limit the number of results returned. schema: type: integer - in: query name: since 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. schema: type: string - in: query name: server description: |- The server to fetch the public room lists from. Defaults to the local server. schema: type: string responses: "200": description: A list of the rooms on the server. content: application/json: 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 description: |- The server to fetch the public room lists from. Defaults to the local server. schema: type: string requestBody: content: application/json: 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: |- An optional string to search for in the room metadata, e.g. name, topic, canonical alias, etc. room_types: type: array x-addedInMatrixVersion: "1.4" items: type: string description: |- An optional list of [room types](/client-server-api/#types) to search for. To include rooms without a room type, specify `null` within this list. When not specified, all applicable rooms (regardless of type) are returned. 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", "room_types": [ null, "m.space" ] }, "include_all_networks": false, "third_party_instance_id": "irc" } description: Options for which rooms to return. required: true responses: "200": description: A list of the rooms on the server. content: application/json: schema: $ref: definitions/public_rooms_response.yaml tags: - Room discovery servers: - url: "{protocol}://{hostname}{basePath}" variables: protocol: enum: - http - https default: https hostname: default: localhost:8008 basePath: default: /_matrix/client/v3