Directory API

Room Alias Directory

Get Room Alias

GET /_matrix/client/v3/directory/room/{roomAlias}
{
  "room_id": "!abc:localhost",
  "servers": ["localhost"]
}

Create Room Alias

PUT /_matrix/client/v3/directory/room/{roomAlias}
{ "room_id": "!abc:localhost" }

Delete Room Alias

DELETE /_matrix/client/v3/directory/room/{roomAlias}

Public Room Directory

List Public Rooms

GET /_matrix/client/v3/publicRooms?limit=50&since=...

Returns published rooms with populated metadata (name, topic, avatar from state events).

{
  "chunk": [
    {
      "room_id": "!abc:localhost",
      "name": "General Chat",
      "topic": "A room for general discussion",
      "avatar_url": "mxc://localhost/thumb",
      "num_joined_members": 42,
      "world_readable": true,
      "guest_can_join": true
    }
  ],
  "next_batch": "...",
  "total_room_count_estimate": 100
}

Search Public Rooms

POST /_matrix/client/v3/publicRooms
{
  "filter": { "generic_search_term": "general" },
  "limit": 50,
  "since": "..."
}

User Directory

Search Users

POST /_matrix/client/v3/user_directory/search
{
  "search_term": "alice",
  "limit": 20
}
{
  "results": [
    {
      "user_id": "@alice:localhost",
      "display_name": "Alice",
      "avatar_url": "mxc://localhost/avatar"
    }
  ],
  "limited": false
}

Third-Party ID (3PID)

Get 3PIDs

GET /_matrix/client/v3/account/3pid

Add 3PID

POST /_matrix/client/v3/account/3pid

Bind 3PID

POST /_matrix/client/v3/account/3pid/bind

Unbind 3PID

POST /_matrix/client/v3/account/3pid/unbind

Request Email Token

POST /_matrix/client/v3/register/email/requestToken

Request MSISDN Token

POST /_matrix/client/v3/register/msisdn/requestToken