---
title: "Lists a server's published room directory with an optional filter"
method: POST
path: "/_matrix/client/v3/publicRooms"
tags: ["Room discovery"]
---

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

`POST /_matrix/client/v3/publicRooms`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/publicRooms`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/publicRooms/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `server` string, mx-server-name

## Request body

- object
  - `filter` object: Filter to apply to the results.
    - `generic_search_term` string: An optional string to search for in the room metadata, e.g. name, topic, canonical alias, etc.
    - `room_types` string[]: An optional list of [room types](https://spec.matrix.org/v1.19/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` boolean: Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to `false`.
  - `limit` integer: Limit the number of results returned.
  - `since` string: 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_id` string: 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`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3thirdpartyprotocols).

## Response `200`

A filtered list of the published rooms on the server.

- object: A list of the published rooms on the server.
  - `chunk` object[], required: A paginated chunk of published rooms.
    - `avatar_url` string, uri: The URL for the room's avatar, if one is set.
    - `canonical_alias` string, mx-room-alias: The canonical alias of the room, if any.
    - `guest_can_join` boolean, required: 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.
    - `join_rule` string: The room's join rule. When not present, the room is assumed to be `public`.
    - `name` string: The name of the room, if any.
    - `num_joined_members` integer, required: The number of members joined to the room.
    - `room_id` string, mx-room-id, required: The ID of the room.
    - `room_type` string: The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.
    - `topic` string: The plain text topic of the room. Omitted if no `text/plain` mimetype exists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).
    - `world_readable` boolean, required: Whether the room may be viewed by users without joining.
  - `next_batch` string: 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` string: 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` integer: An estimate on the total number of published rooms, if the server has an estimate.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)