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

  • Deprecations

    • 1101: Deprecate the sender_key and device_id on m.megolm.v1.aes-sha2 events, and the sender_key on m.room_key_request to-device messages, as per MSC3700.

  • Backwards Compatible Changes

    • 1002: Make from optional on GET /_matrix/client/v3/messages to allow requesting events from the start or end of the room history, as per MSC3567.
    • 1056: Add refresh tokens, per MSC2918.
    • 1062: Relax the restrictions on Rich Replies, as per MSC3676.
    • 1062: Describe a structured system for event relationships, as per MSC2674.
    • 1062: Describe how relationships between events can be “aggregated”, as per MSC2675 and MSC3666.
    • 1099: Add support for a new knock_restricted join rule in supported room versions, as per MSC3787.
    • 1113: Add refresh tokens, per MSC2918.

  • Spec Clarifications

    • 1003: Adjust the OpenAPI specification so that the type Flow information is explicitly defined when the client-server API is rendered.
    • 1021: Correct the default value for invite where it is not specified in an m.room.power_levels event.
    • 1032: Update various links which pointed to the old matrix-doc github repository.
    • 1035: Removed m.room.message.feedback per MSC3582.
    • 1051: Fix various typos throughout the specification.
    • 1054: Fix various typos throughout the specification.
    • 1059: Fix various typos throughout the specification.
    • 1081: Fix various typos throughout the specification.
    • 1097: Fix various typos throughout the specification.
    • 1100: Clarify that state keys starting with @ are in fact reserved. Regressed from #3658.
    • 1110: Fix various typos throughout the specification.
    • 1115: Fix various typos throughout the specification.
    • 1127: Fix various typos throughout the specification.
    • 3669: Remove unenforced size limit on the name field of m.room.name events.
    • 3679: Remove erroneous room_id field from examples of m.read, m.typing in /sync and m.fully_read in room account data.
    • 3681: Fix various typos throughout the specification.
    • 3690: Clarify the behaviour of event_match in push rule conditions.
    • 3708: Fix various typos throughout the specification.
    • 3711: Fix incorrectly referenced m.login.appservice login identifier, instead using m.login.application_service.
    • 3730: Fix membership state transitions to denote that invite->knock and external->leave are valid transitions.
    • 987: Clarify that the url field in m.room.avatar events is not required.
    • 989: Clarify that the type in user-interactive authentication can be omitted.

Server-Server API

  • Backwards Compatible Changes

    • 1067: Add a destination property to the Authorization header, as per MSC3383.

  • Spec Clarifications

    • 1032: Update various links which pointed to the old matrix-doc github repository.
    • 1038: Clarify the format for the Authorization header.
    • 1045: Clarify what a “valid event” means when performing checks on a received PDU.
    • 1055: Clarify that valid_until_ts is in milliseconds, like other timestamps used in Matrix.
    • 1067: Clarify the format for the Authorization header.
    • 1070: Clarify that checks on PDUs should refer to the state before an event.
    • 1099: Clarify the historical handling of non-integer power levels.
    • 1110: Fix various typos throughout the specification.
    • 3703: Correct misleading text for /send_join response.
    • 3727: Clarify that the content for X-Matrix signature validation is the parsed JSON body.
    • 998: Remove largely unused origin field from PDUs.

Application Service API

  • Backwards Compatible Changes

Identity Service API

Push Gateway API

Room Versions

  • Backwards Compatible Changes

  • Spec Clarifications

    • 1037: Improve readability and understanding of the state resolution algorithms.
    • 1042: Improve readability and understanding of the state resolution algorithms.
    • 1043: Improve readability and understanding of the state resolution algorithms.
    • 1050: Improve readability of the authorization rules.
    • 1093: For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event.
    • 1099: Clarify that room versions 1 through 9 accept stringy power levels, as noted by MSC3667.
    • 1103: For all room versions: Add m.federate to the authorization rules, as originally intended.
    • 1120: Improve readability and understanding of the state resolution algorithms.
    • 3737: For room versions 7, 8, 9, and 10: fix join membership authorization rules when join_rule is knock.

Appendices

v1.2

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

Client-Server API

Breaking Changes

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

New Endpoints

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

Backwards Compatible Changes

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

Spec Clarifications

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

Server-Server API

New Endpoints

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

Backwards Compatible Changes

Spec Clarifications

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

Application Service API

Spec Clarifications

  • 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. (#3658)
  • Fix the rendering of the responses for various API endpoints. (#3674)
  • Correct the documentation for the response value for GET /_matrix/app/v1/thirdparty/protocol/{protocol}. (#3675)

Identity Service API

Backwards Compatible Changes

  • Add the room_type to stored invites as per MSC3288. (#3610)

Spec Clarifications

  • Fix the rendering of the responses for various API endpoints. (#3674)

Push Gateway API

Spec Clarifications

  • Fix the rendering of the responses for various API endpoints. (#3674)

Room Versions

Backwards Compatible Changes

Spec Clarifications

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

Appendices

Backwards Compatible Changes

  • Describe “Common Namespaced Identifier Grammar” as per MSC2758. (#3171)
  • Describe the matrix: URI scheme as per MSC2312. (#3608)

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.