Matrix Specification

The Matrix specification defines how Matrix works. Understanding it helps you build better applications and troubleshoot issues.

Spec Structure

The specification is divided into several APIs:

API	Purpose
Client-Server	Client ↔ Homeserver
Server-Server	Homeserver ↔ Homeserver (Federation)
Application Service	Bridges & bots
Identity Service	3PID lookup
Push Gateway	Push notifications

Current Version

The latest stable version is v1.11 (as of 2024).

Check the current version at spec.matrix.org.

Room Versions

Room behavior is defined by room versions:

Version	Features	Status
1-5	Legacy	Deprecated
6	Stricter validation	Deprecated
7-8	Knock support	Deprecated
9	Restricted rooms	Current
10	Knock + restricted	Current
11	Latest features	Latest

Creating Rooms

Specify room version when creating:

{
  "room_version": "11",
  "name": "My Room"
}

MSCs (Matrix Spec Changes)

New features are proposed through MSCs:

1. Proposal - Write MSC document
2. Review - Community feedback
3. FCP - Final Comment Period
4. Merge - Added to spec

Notable MSCs

MSC	Feature
MSC1772	Spaces
MSC2674	Event relationships (threads)
MSC3401	Native group calls
MSC3575	Sliding Sync

Track MSCs at matrix.org/docs/spec/proposals.

Reading the Spec

Endpoints

Each endpoint is documented with:

• HTTP method and path
• Request parameters
• Response format
• Error codes

Example:

POST /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}

Event Schemas

Events have defined schemas:

{
  "type": "m.room.message",
  "content": {
    "msgtype": "m.text",
    "body": "Hello"
  }
}

Useful Spec Sections

For Client Developers

• Syncing
• Rooms
• Events
• E2EE

For Server Admins

• Server discovery
• Authentication
• Key management

Resources

• Matrix Spec - Full specification
• Spec Proposals - MSCs
• #matrix-spec:matrix.org - Discussion

---

Continue: Client-Server API | Server-Server API