You're looking at an old version of this specification.

Switch to the current stable release.

Changelog

This is version v1.2 of the Matrix specification.

Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.2
Release dateFebruary 02, 2022

Changes since last release

Client-Server API

  • Breaking Changes

    • 3524: The prev_content field is now returned inside the unsigned property of events, rather than at the top level, as per MSC3442.
    • 3624: The aliases property from the chunks returned by /publicRooms, as per MSC2432.

  • New Endpoints

    • 3610: Add the Space Hierarchy API (GET /_matrix/client/v1/rooms/{roomId}/hierarchy) as per MSC2946.
    • 3616: Add /_matrix/client/v1/register/m.login.registration_token/validity as per MSC3231.

  • Backwards Compatible Changes

    • 3324: Extend /_matrix/client/r0/login to accept a m.login.appservice, as per MSC2778.
    • 3387: Add support for restricted rooms as per MSC3083, MSC3289, and MSC3375.
    • 3605: Add is_guest to /account/whoami as per MSC3069.
    • 3605: Expand guest access to sending any room event and state event as per MSC3419.
    • 3610: Add Spaces and room types as per MSC1772 and MSC2946.
    • 3614: Add new m.set_displayname, m.set_avatar_url, and m.3pid_changes capabilities as per MSC3283.
    • 3615: Add support for fallback keys (optional keys used once one-time keys run out), as per MSC2732.
    • 3616: Add token-authenticated registration support as per MSC3231.

  • Spec Clarifications

    • 3481: Make AesHmacSha2KeyDescription consistent with KeyDescription in marking name as optional.
    • 3482: Fix various typos throughout the specification.
    • 3492: Explicitly mention RFC5870 in the definition of m.location events
    • 3495: Fix various typos throughout the specification.
    • 3509: Fix various typos throughout the specification.
    • 3530: Add 403 M_FORBIDDEN error code to /profile/{userId} as per MSC3550.
    • 3535: Fix various typos throughout the specification.
    • 3543: Clarify the description of the /sync API, including a fix to an ASCII art diagram.
    • 3562: Clarify that base_url in client well_known may or may not include trailing slash.
    • 3573: Clarify which signature to check when decrypting m.olm.v1.curve25519-aes-sha2 messages.
    • 3591: Fix various typos throughout the specification.
    • 3601: Fix various typos throughout the specification.
    • 3606: Clarify what “Stripped State” is and what purpose it serves, as per MSC3173.
    • 3611: Fix various typos throughout the specification.
    • 3636: Clarify how to interpret missing one-time key counts.
    • 3650: Correct the schema for the responses for various API endpoints.
    • 3652: Clarify that group mentions are no longer in the specification.
    • 3658: Distinguish between “federation” event format as exchanged by the Federation API, and the “client” event formats as used in the client-server and AS APIs.
    • 3671: Fix various typos throughout the specification.
    • 3674: Fix the rendering of the responses for various API endpoints.
    • 3680: Fix various typos throughout the specification.

Server-Server API

  • New Endpoints

    • 3610: Add the Space Hierarchy API (GET /_matrix/federation/v1/hierarchy/{roomId}) as per MSC2946.
    • 3660: Add the Space Hierarchy API (GET /_matrix/federation/v1/hierarchy/{roomId}) as per MSC2946.

  • Backwards Compatible Changes

  • Spec Clarifications

    • 3527: Fix various typos throughout the specification.
    • 3583: Clarify that GET /_matrix/federation/v1/event_auth/{roomId}/{eventId} does not return the auth chain for the full state of the room.
    • 3674: Fix the rendering of the responses for various API endpoints.

Application Service API

  • Spec Clarifications

    • 3658: Distinguish between “federation” event format as exchanged by the Federation API, and the “client” event formats as used in the client-server and AS APIs.
    • 3674: Fix the rendering of the responses for various API endpoints.
    • 3675: Correct the documentation for the response value for GET /_matrix/app/v1/thirdparty/protocol/{protocol}.

Identity Service API

  • Backwards Compatible Changes

  • Spec Clarifications

    • 3674: Fix the rendering of the responses for various API endpoints.

Push Gateway API

  • Spec Clarifications

    • 3674: Fix the rendering of the responses for various API endpoints.

Room Versions

  • Backwards Compatible Changes

  • Spec Clarifications

    • 3432: Fully specify room versions to indicate what exactly is carried over from parent versions.
    • 3501: Clarifications to sections on event IDs and event formats.
    • 3522: Remove a number of fields which were incorrectly shown to form part of the unsigned data of a Federation PDU.
    • 3661: Fully specify room versions to indicate what exactly is carried over from parent versions.
    • 3683: Fix heading order of room version specifications to be consistent.
    • 3683: Add missing “Signing key validity period” section to room version 6.
    • 3694: Fix auth rules to allow membership of knock -> leave in v7, v8, and v9.

Appendices

  • Backwards Compatible Changes

v1.1

Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.1
Release dateNovember 09, 2021

Client-Server API

Breaking Changes

  • Document curve25519-hkdf-sha256 key agreement method for SAS verification, and deprecate old method as per MSC2630. (#2687)
  • Add m.key.verification.ready and m.key.verification.done to key verification framework as per MSC2366. (#3139)

Deprecations

  • Deprecate starting verifications that don’t start with m.key.verification.request as per MSC3122. (#3199)

New Endpoints

  • Add key backup (/room_keys/*) endpoints as per MSC1219. (#2387, #2639)
  • Add POST /keys/device_signing/upload and POST /keys/signatures/upload as per MSC1756. (#2536)
  • Add /knock endpoint as per MSC2403. (#3154)
  • Add /login/sso/redirect/{idpId} as per MSC2858. (#3163)

Removed Endpoints

  • Remove unimplemented m.login.oauth2 and m.login.token user-interactive authentication mechanisms as per MSC2610 and MSC2611. (#2609)

Backwards Compatible Changes

  • Document how clients can advise recipients that it is withholding decryption keys as per MSC2399. (#2399)
  • Add cross-signing properties to the response of POST /keys/query as per MSC1756. (#2536)
  • Document Secure Secret Storage and Sharing as per MSC1946 and MSC2472. (#2597)
  • Add a device_id parameter to login fallback as per MSC2604. (#2709)
  • Added a common set of translations for SAS Emoji. (#2728)
  • Added support for reason on all membership events and related endpoints as per MSC2367. (#2795)
  • Add a 404 M_NOT_FOUND error to push rule endpoints as per MSC2663. (#2796)
  • Make reason and score parameters optional in the content reporting API as per MSC2414. (#2807)
  • Allow guests to get the list of members for a room as per MSC2689. (#2808)
  • Add support for spoilers as per MSC2010 and MSC2557, and color attribute as per MSC2422. (#3098)
  • Add <details> and <summary> to the suggested HTML subset as per MSC2184. (#3100)
  • Add key verification using in-room messages as per MSC2241. (#3139, #3150)
  • Add information about using SSSS for cross-signing and key backup. (#3147)
  • Add key verification method using QR codes as per MSC1544. (#3149)
  • Document how clients can simplify usage of Secure Secret Storage as per MSC2874. (#3151)
  • Add support for knocking, as per MSC2403. (#3154, #3254)
  • Multiple SSO providers are possible through m.login.sso as per MSC2858. (#3163)
  • Add device_id to /account/whoami response as per MSC2033. (#3166)
  • Downgrade identity server discovery failures to FAIL_PROMPT as per MSC2284. (#3169)
  • Re-version all endpoints to be v3 as a starting point instead of r0 as per MSC2844. (#3421)

Spec Clarifications

  • Fix issues with age and unsigned being shown in the wrong places. (#2591)
  • Fix definitions for room version capabilities. (#2592)
  • Fix various typos throughout the specification. (#2594, #2599, #2809, #2878, #2885, #2888, #3116, #3339)
  • Clarify link to OpenID Connect specification. (#2605)
  • Clarify the behaviour of SSO login and UI-Auth. (#2608)
  • Remove spurious room_id from /sync examples. (#2629)
  • Reorganize information in Push Notifications module for clarity. (#2634)
  • Improve consistency and clarity of event schema titles. (#2647)
  • Fix schema issues in m.key.verification.accept and secret storage. (#2653)
  • Reword “UI Authorization” to “User-Interactive Authentication” to be more clear. (#2667)
  • Fix schemas for push rule actions to represent their alternative object form. (#2669)
  • Fix usage of highlight tweak for consistency. (#2670)
  • Clarify the behaviour of state for /sync with lazy-loading. (#2754)
  • Clarify description of m.room.redaction event. (#2814)
  • Mark messages as a required JSON body field in PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId} calls. (#2928)
  • Correct examples of client_secret request body parameters so that they do not include invalid characters. (#2985)
  • Fix example MXC URI for m.presence. (#3091)
  • Clarify that event bodies are untrusted, as per MSC2801. (#3099)
  • Fix the maximum event size restriction (65535 bytes -> 65536). (#3127)
  • Update Access-Control-Allow-Headers recommendation to fit CORS specification. (#3225)
  • Explicitly state that replacement_room is a room ID in m.room.tombstone events. (#3233)
  • Clarify that all request bodies are required. (#3238, #3332)
  • Add missing titles to some scheams. (#3330)
  • Add User-Interactive Authentication fields to cross-signing APIs as per MSC1756. (#3331)
  • Mention that a canonical alias event should be added when a room is created with an alias. (#3337)
  • Add an ‘API conventions’ section to the Appendices. (#3350)
  • Clarify the documentation around the pagination tokens used by /sync, /rooms/{room_id}/messages, /initialSync, /rooms/{room_id}/initialSync, and /notifications. (#3353)
  • Remove the inaccurate ‘Pagination’ section. (#3366)
  • Clarify how redacted_because is meant to work. (#3411)
  • Remove extraneous mimetype from EncryptedFile examples, as per MSC2582. (#3412)
  • Describe how MSC2844 affects the /versions endpoint. (#3420)
  • Fix documentation errors around threepid_creds. (#3471)

Server-Server API

New Endpoints

  • Add /make_knock and /send_knock endpoints as per MSC2403. (#3154)

Backwards Compatible Changes

  • Add cross-signing information to GET /user/keys and GET /user/devices/{userId}, m.device_list_update EDU, and a new m.signing_key_update EDU as per MSC1756. (#2536)
  • Add support for knocking, as per MSC2403. (#3154)

Spec Clarifications

  • Specify that GET /_matrix/federation/v1/make_join/{roomId}/{userId} can return a 404 if the room is unknown. (#2688)
  • Fix various typos throughout the specification. (#2888, #3116, #3128, #3207)
  • Correct the /_matrix/federation/v1/user/devices/{userId} response which actually returns "self_signing_key" instead of "self_signing_keys". (#3312)
  • Explain the reasons why <hostname> TLS certificate is needed rather than <delegated_hostname> for SRV delegation. (#3322)
  • Tweak the example PDU diagram to better demonstrate situations with multiple prev_events. (#3340)

Application Service API

Spec Clarifications

  • Fix various typos throughout the specification. (#2888)

Identity Service API

New Endpoints

  • Add GET /_matrix/identity/versions API as per MSC2320. (#3101)

Removed Endpoints

  • The v1 identity service API has been removed in favour of the v2 API, as per MSC2713. (#3170)

Spec Clarifications

  • Fix various typos throughout the specification. (#2888)
  • Clarify that some identifiers must be case folded prior to processing, as per MSC2265. (#3167, #3176)
  • Describe how MSC2844 affects the /versions endpoint. (#3459)

Push Gateway API

Spec Clarifications

  • Clarify where to get information about the various parameter values for the notify endpoint. (#2763)

Historical versions

Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs.