# 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/v3 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" 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 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: {} schema: type: object 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" 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 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: |- 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" } responses: 200: description: A list of the rooms on the server. schema: $ref: "definitions/public_rooms_response.yaml" tags: - Room discovery