matrix-spec-proposals/api/client-server/list_public_rooms.yaml

# 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 Creation API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
paths:
  "/publicRooms":
    get:
      summary: Lists the public rooms on the server.
      description: |-
        Lists the public rooms on the server.

        This API returns paginated responses.
      parameters:
        - in: query
          name: limit
          type: number
          description: |-
            Limit the number of results returned, ordered by number of
            memebers in the room. Defaults to no limit.
        - in: query
          name: since
          type: string
          description: |-
            A pagination token from a previous request, allowing clients to
            get the next batch of rooms.
        - 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:
            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"]
                  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. May be null.
                    name:
                      type: string
                      description: |-
                        The name of the room, if any. May be null.
                    num_joined_members:
                      type: number
                      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. May be null.
                    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: number
                description: |-
                   An estimate on the total number of public rooms.
          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
              }
        400:
          description: >
            The request body is malformed or the room alias specified is already taken.
    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.
      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: number
                description: |-
                  Limit the number of results returned, ordered by number of
                  memebers in the room. Defaults to no limit.
              since:
                type: string
                description: |-
                  A pagination token from a previous request, allowing clients to
                  get the next batch of rooms.
              filter:
                type: object
                title: "Filter"
                description: |-
                  Optional filtering of the returned rooms.
                properties:
                    generic_search_term:
                      type: string
                      description: |-
                        A string to search for in the room metadata, e.g. name,
                        topic, canonical alias etc. (Optional).
            example: |-
              {"limit": 10, "filter": {"generic_search_term": "foo"}}
      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"]
                  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. May be null.
                    name:
                      type: string
                      description: |-
                        The name of the room, if any. May be null.
                    num_joined_members:
                      type: number
                      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. May be null.
                    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: number
                description: |-
                   An estimate on the total number of public rooms.
          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
              }
        400:
          description: >
            The request body is malformed or the room alias specified is already taken.
      tags:
        - Room discovery