Matrix Specification

The Client-Server API is the primary interface for Matrix clients to interact with a homeserver. It enables clients to:

• Send messages.
• Control rooms.
• Synchronize conversation history.

The API is designed to accommodate two distinct client architectures:

1. Lightweight clients: These clients store no local state and lazy-load data from the server as needed.
2. Heavyweight clients: These clients maintain a full, local, persistent copy of the server state.

Room Version 2 is an evolution of Room Version 1. The primary difference is an improved state resolution algorithm. Most other components, including event formats, redactions, and authorization rules, remain consistent with Version 1.

Note for Clients: There are no specific client-side changes introduced by this version. Clients implementing redaction logic locally should follow the standard redaction algorithm described in the specification.

Room Version 12 introduces several breaking changes and improvements over Version 11:

• Room ID Format: Room IDs no longer include a domain component. They are now a hash of the m.room.create event.
• Room Creators: The definition of a 'room creator' has expanded. It now includes the sender of the m.room.create event and any users listed in the additional_creators field within the m.room.create event's content.
• Creator Power Levels: Room creators are granted infinite power levels. They cannot be modified via m.room.power_levels events, and their status cannot be changed after room creation.

Room Version 1 is the foundational version for Matrix rooms. It contains the core building blocks used by subsequent versions.

Key considerations for developers:

• Clients: Should refer to the specific redaction algorithms defined for v1 to ensure local implementation matches server behavior.
• Servers: Must identify the room version before executing algorithms, as v1 uses specific logic for event IDs, authorization, and state resolution that may differ from newer versions.
• Stability Warning: Room Version 1 is known to have bugs in its state resolution algorithm that can cause room state to reset (e.g., users being removed, power levels being lost, or room names/topics reverting). These issues are addressed in Room Version 2.

Matrix client-server communication is based on exchanging JSON objects over HTTP APIs.

Key Requirements:

• Protocol: HTTPS is recommended; plain HTTP is discouraged.
• Authentication: Clients use opaque access_token strings.
• Content Type: Clients should use application/json for requests with JSON bodies. Servers MUST include application/json for all JSON responses.
• Encoding: All JSON data (requests and responses) must be encoded using UTF-8.
• Request Bodies: Most POST and PUT endpoints require a JSON request body.

Exceptions to Request Body rules:

• POST /_matrix/media/v3/upload and PUT /_matrix/media/v3/upload/{serverName}/{mediaId}: The request body is the uploaded media itself.
• POST /_matrix/client/v3/logout and POST /_matrix/client/v3/logout/all: These take an empty request body.

Megolm is an AES-based cryptographic ratchet designed for group communications where a large number of recipients make peer-to-peer encryption (like Olm) impractical.

Key characteristics:

• Scalability: Designed for many recipients per message.
• Decryption Reuse: Allows a recipient to decrypt messages multiple times (e.g., storing ciphertext on an untrusted server while keeping session keys locally).
• Secrecy: Provided by a one-way ratchet that derives distinct message keys and can only be wound forwards.
• Authenticity: Provided via Ed25519 signatures.
• Deniability: Inherited from the secure peer-to-peer channel used to share session data (e.g., Olm).

Users can label rooms using tags. Tags are namespaced strings that are private to the user (visible only to them across all their devices).

Tags are implemented as a single m.tag event located in the account_data section of a room. The event content contains a tags key, which is an object mapping tag names to metadata objects.

Tag Metadata:

• order (number): A value between 0 and 1 used to sort rooms with that tag. Lower numbers (e.g., 0.2) are displayed before higher numbers (e.g., 0.7). Rooms without an order key should be displayed after rooms that do have one.

Constraints:

• Tag names MUST NOT exceed 255 bytes.

{
  "events": [
    {
      "type": "m.tag",
      "content": {
        "tags": {
          "m.favourite": {
            "order": 0.1
          },
          "u.work": {
            "order": 0.5
          }
        }
      }
    }
  ]
}

In Room Version 12, a 'room creator' is not just the single sender of the creation event. To correctly identify all creators, a client must look at the m.room.create event and include:

1. The sender of the m.room.create event.
2. Any user IDs found in the additional_creators field within the content object of the m.room.create event (if present).

Note that these creators have infinite power levels and are exempt from m.room.power_levels restrictions.