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

Switch to the current stable release.

Changelog

This is version v1.1 of the Matrix specification.

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

Changes since last release

Client-Server API

  • Breaking Changes

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

  • Deprecations

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

  • New Endpoints

  • Removed Endpoints

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

  • 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 as per MSC1756.
    • 2597: Document Secure Secret Storage and Sharing as per MSC1946 and MSC2472.
    • 2709: Add a device_id parameter to login fallback as 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 as per MSC2414.
    • 2808: Allow guests to get the list of members for a room as per MSC2689.
    • 3098: Add support for spoilers as per MSC2010 and MSC2557, and color attribute as per 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 as per MSC1544.
    • 3150: Add key verification using in-room messages as per MSC2241.
    • 3151: Document how clients can simplify usage of Secure Secret Storage as per 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.
    • 3421: Re-version all endpoints to be v3 as a starting point instead of r0 as per MSC2844.

  • 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 spurious room_id from /sync examples.
    • 2634: Reorganize information in Push Notifications module for clarity.
    • 2647: Improve consistency and clarity of event schema titles.
    • 2653: Fix schema issues in m.key.verification.accept and secret storage.
    • 2667: Reword “UI Authorization” to “User-Interactive Authentication” to be more clear.
    • 2669: Fix schemas for push rule actions to represent their alternative object form.
    • 2670: Fix usage of highlight tweak for consistency.
    • 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 replacement_room is a room ID in m.room.tombstone events.
    • 3238: Clarify that all request bodies are required.
    • 3330: Add missing titles to some scheams.
    • 3331: Add User-Interactive Authentication fields to cross-signing APIs as per MSC1756.
    • 3332: Clarify that all request bodies are required.
    • 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.
    • 3412: Remove extraneous mimetype from EncryptedFile examples, as per MSC2582.
    • 3420: Describe how MSC2844 affects the /versions endpoint.
    • 3471: Fix documentation errors around threepid_creds.

Server-Server API

  • New Endpoints

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

  • Backwards Compatible Changes

    • 2536: 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.
    • 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.
    • 3459: Describe how MSC2844 affects the /versions endpoint.

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.