Matrix Specification

Matrix defines a set of open APIs for decentralised communication, suitable for securely publishing, persisting and subscribing to data over a global open federation of servers with no single point of control. Uses include Instant Messaging (IM), Voice over IP (VoIP) signalling, Internet of Things (IoT) communication, and bridging together existing communication silos - providing the basis of a new open real-time communication ecosystem.

Introduction to Matrix provides a full introduction to Matrix and the spec.

Matrix APIs

The following APIs are documented in this specification:

API Version Description
Client-Server API r0.2.0 Interaction between clients and servers
Server-Server API unstable Federation between servers
Application Service API unstable Privileged server plugins
Identity Service API unstable Mapping of third party IDs to Matrix IDs
Push Gateway API unstable Push notifications for Matrix events

Appendices with supplemental information not specific to one of the above APIs are also available.

Specification Versions

The specification for each API is versioned in the form rX.Y.Z.
  • A change to X reflects a breaking change: a client implemented against r1.0.0 may need changes to work with a server which supports (only) r2.0.0.
  • A change to Y represents a change which is backwards-compatible for existing clients, but not necessarily existing servers: a client implemented against r1.1.0 will work without changes against a server which supports r1.2.0; but a client which requires r1.2.0 may not work correctly with a server which implements only r1.1.0.
  • A change to Z represents a change which is backwards-compatible on both sides. Typically this implies a clarification to the specification, rather than a change which must be implemented.