You're looking at an unstable version of this specification. Unstable specifications may change at any time without notice.

Switch to the current stable release.

Changelog

This is the unstable version of the Matrix specification.

This changelog lists changes made since the last release of the specification.

Changes since last release

Client-Server API

  • Spec Clarifications

    • 3481: Make AesHmacSha2KeyDescription consistent with KeyDescription in marking name as optional.
    • 3482: Fix various typos throughout the specification.
    • 3492: Explicity mention RFC5870 in the definition of m.location events
    • 3495: Fix various typos throughout the specification.
    • 3509: Fix various typos throughout the specification.

Server-Server API

Application Service API

Identity Service API

Push Gateway API

Room Versions

  • Spec Clarifications

    • 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.

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.