MAmatrix
Room discovery

Lists a server's published room directory with an optional filter

Lists a server's published room directory with an optional filter.

This API returns paginated responses.

[Changed in v1.19] The server determines the order of the rooms returned by this endpoint. Previously, rooms were ordered with the largest joined member count first. Continuing to order by largest first or another stable order is recommended.

post/_matrix/client/v3/publicRooms

Request

Query parameters

serverstring mx-server-name

The server to fetch the published room directory from. Defaults to the local server. Case sensitive.

Request body

include_all_networksboolean

Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false.

limitinteger

Limit the number of results returned.

sincestring

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.

third_party_instance_idstring

The specific third-party network/protocol to request from the homeserver. Can only be used if include_all_networks is false.

This is the instance_id of a Protocol Instance returned by GET /_matrix/client/v3/thirdparty/protocols.

Example request

{
  "filter": {
    "generic_search_term": "foo",
    "room_types": [
      null,
      "m.space"
    ]
  },
  "include_all_networks": false,
  "limit": 10,
  "third_party_instance_id": "irc-freenode"
}

Response

A filtered list of the published rooms on the server.

next_batchstring

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_batchstring

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_estimateinteger

An estimate on the total number of published rooms, if the server has an estimate.

Example response

{
  "chunk": [
    {
      "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "join_rule": "public",
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "room_type": "m.space",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}

Changes

No recorded changes to this operation across all 1 revision of this API.