---
title: "Public rooms directory"
method: GET
path: "/_matrix/federation/v1/publicRooms"
tags: ["matrix-s2s"]
---

# Public rooms directory

`GET /_matrix/federation/v1/publicRooms`

## Request

- The document declares no server URL.
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/etkecc/apis/matrix-rooms-search-api/docs/_matrix/federation/v1/publicRooms/get.ts> (a function with typed inputs; its response is checked against the schema)

Our slice of the federation public-rooms directory: the rooms we have crawled and indexed. Authenticated federation endpoint, so a missing or invalid X-Matrix signature is a 401. GET (query params) and POST (JSON filter body) share one handler, and a malformed POST body is logged then ignored, so you get the unfiltered listing rather than an error.

## Request body

- GithubComEtkeccMrsInternalModelRoomDirectoryRequest
  - `filter` GithubComEtkeccMrsInternalModelRoomDirectoryFilter
    - `generic_search_term` string
    - `room_types` string[]
  - `limit` integer
  - `since` string

## Response `200`

Our indexed slice of the public-rooms directory

- GithubComEtkeccMrsInternalModelRoomDirectoryResponse
  - `chunk` GithubComEtkeccMrsInternalModelRoomDirectoryRoom[]
    - `avatar_url` string
    - `canonical_alias` string
    - `guest_can_join` boolean
    - `join_rule` string
    - `name` string
    - `num_joined_members` integer
    - `room_id` string
    - `room_type` string
    - `topic` string
    - `world_readable` boolean
  - `next_batch` string
  - `prev_batch` string
  - `total_room_count_estimate` integer

## Other responses

- `401`: Federation auth failed (missing or invalid X-Matrix signature)

## Changes

- **2026-07-08** `ae3c2fd65492`: 1 info
  - endpoint added
- **2024-08-20** `4009b08a3a5a`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/etkecc/apis/matrix-rooms-search-api/changes/_matrix/federation/v1/publicRooms/get.md)

---

[API](https://skmtc.dev/etkecc/apis/matrix-rooms-search-api.md) - [All operations](https://skmtc.dev/etkecc/apis/matrix-rooms-search-api/llms.txt) - [OpenAPI document](https://skmtc.dev/etkecc/apis/matrix-rooms-search-api/revisions/fafe2e40cd8c?raw)