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

  • Breaking Changes

    • 2687: Document curve25519-hkdf-sha256 key agreement method for SAS verification, and deprecate old method (MSC2630).
    • 3139: Add m.key.verification.ready and m.key.verification.done to key verification framework as per MSC2366.
    • 3327: Fix key_backup operation IDs in OpenAPI spec.

  • New Endpoints

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

  • Removed Endpoints

    • 2609: Remove unimplemented m.login.oauth2 and m.login.token user-interactive authentication mechanisms.

  • Backwards Compatible Changes

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

  • Spec Clarifications

    • 2591: Fix issues with age and unsigned being shown in the wrong places.
    • 2592: Fix definitions for room version capabilities.
    • 2594: Fix various typos throughout the specification.
    • 2599: Fix various typos throughout the specification.
    • 2605: Clarify link to OpenID Connect specification.
    • 2608: Clarify the behaviour of SSO login and UI-Auth.
    • 2629: Remove room_id from /sync examples.
    • 2634: Minor clarifications to the “Push Notifications” module.
    • 2639: Fixed some errors in the key backup spec.
    • 2647: Improve consistency and clarity of event schema title s.
    • 2653: Fix some errors in the end-to-end encryption spec.
    • 2667: Reword “UI Authorization” to “User-Interactive Authentication” to be more clear.
    • 2669: Fix types of push rules' actions; they can be objects as well as strings.
    • 2670: Minor clarifications to the “Push Notifications” module.
    • 2754: Clarify the behaviour of state for /sync with lazy-loading.
    • 2809: Fix various typos throughout the specification.
    • 2814: Clarify description of m.room.redaction event.
    • 2878: Fix various typos throughout the specification.
    • 2885: Fix various typos throughout the specification.
    • 2888: Fix various typos throughout the specification.
    • 2928: Mark messages as a required JSON body field in PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId} calls.
    • 2985: Correct examples of client_secret request body parameters so that they do not include invalid characters.
    • 3091: Fix example MXC URI for m.presence.
    • 3099: Clarify that event bodies are untrusted, as per MSC2801.
    • 3116: Fix various typos throughout the specification.
    • 3127: Fix the maximum event size restriction (65535 bytes -> 65536).
    • 3225: Update Access-Control-Allow-Headers recommendation to fit CORS specification.
    • 3233: Explicitly state that replacment_room is a room ID in m.room.tombstone events.
    • 3238: Clarify that all request bodies are required.
    • 3330: Add titles for OpenAPI objects.
    • 3331: Add auth property to UIA endpoint uploadCrossSigningKeys.
    • 3332: Clarify that all request bodies are required.
    • 3336: Disambiguate getEvents and peekEvents, and include both in swagger.
    • 3337: Mention that a canonical alias event should be added when a room is created with an alias.
    • 3339: Fix various typos throughout the specification.
    • 3350: Add an ‘API conventions’ section to the Appendices.
    • 3353: Clarify the documentation around the pagination tokens used by /sync, /rooms/{room_id}/messages, /initialSync, /rooms/{room_id}/initialSync, and /notifications.
    • 3366: Remove the inaccurate ‘Pagination’ section.
    • 3411: Clarify how redacted_because is meant to work.

Server-Server API

  • New Endpoints

    • 3154: Add /make_knock and /send_knock endpoints as per MSC2403.

  • Backwards Compatible Changes

    • 2536:

      Add cross-signing:

      • Add properties to the response of GET /user/keys and GET /user/devices/{userId}.
      • The m.device_list_update EDU is sent when a device gets a new signature.
      • A new m.signing_key_update EDU is sent when a user’s cross-signing keys are changed.

      per MSC1756.

    • 3154: Add support for knocking, as per MSC2403.

  • Spec Clarifications

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

Application Service API

  • Spec Clarifications

    • 2888: Fix various typos throughout the specification.

Identity Service API

  • New Endpoints

  • Removed Endpoints

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

  • Spec Clarifications

    • 2888: Fix various typos throughout the specification.
    • 3167: Clarify that some identifiers must be case folded prior to processing, as per MSC2265.
    • 3176: Clarify that some identifiers must be case folded prior to processing, as per MSC2265.

Push Gateway API

  • Spec Clarifications

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

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.