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

Switch to the current stable release.

Changelog

This is version v1.4 of the Matrix specification.

Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.4
Release dateSeptember 29, 2022

Changes since last release

Client-Server API

  • Removed Endpoints

    • 1196: Remove unused policy room sharing mechanism, as per MSC3844.

  • Backwards Compatible Changes

    • 1190: Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786.
    • 1197: Add Cross-Origin-Resource-Policy (CORP) headers to media repository, as per MSC3828.
    • 1198: Copy a room’s type when upgrading it, as per MSC3818.
    • 1199: Add room_types filter and room_type response to /publicRooms, as per MSC3827.
    • 1201: Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786.
    • 1211: Add m.replace relations (event edits), as per MSC2676.
    • 1216: Add m.read.private receipts, as per MSC2285.
    • 1216: Make m.fully_read optional on /read_markers, as per MSC2285.
    • 1216: Allow m.fully_read markers to be set from /receipts, as per MSC2285.
    • 1254: Add threading via m.thread relations, as per MSC3440, MSC3816, MSC3856, and MSC3715.
    • 1255: Add per-thread notifications and read receipts, as per MSC3771 and MSC3773.

  • Spec Clarifications

    • 1084: Mention that the /rooms/{roomId}/invite endpoint will return a 200 response if the user is already invited to the room.
    • 1135: Fix various typos throughout the specification.
    • 1155: Describe return codes for account data endpoints, and clarify that per-room data does not inherit from the global data.
    • 1161: Fix various typos throughout the specification.
    • 1164: Fix various typos throughout the specification.
    • 1165: Clarify that policy rule globs work like ACL globs. Contributed by Nico.
    • 1166: Clarify the format of some structures in the End-to-end encryption module.
    • 1170: Fix various typos throughout the specification.
    • 1174: Add HTML anchors for object definitions in the formatted specification.
    • 1179: Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions.
    • 1180: Fix various typos throughout the specification.
    • 1185: Update “API Standards” section to clarify how JSON is used.
    • 1210: Clarify that the “device_id”, “user_id” and “access_token” fields are required in the response body of POST /_matrix/client/v3/login.
    • 1215: Fix various typos throughout the specification.
    • 1236: Reinforce the relationship of refreshed access tokens to transaction IDs.
    • 1238: Fix various typos throughout the specification.
    • 1240: Clarify enum values by separating possible values with commas.
    • 1243: Fix various typos throughout the specification.
    • 1261: Add thread_id to the /receipt endpoint, as per MSC3771
    • 1263: Fix various typos throughout the specification.

Server-Server API

  • Backwards Compatible Changes

  • Spec Clarifications

    • 1174: Add HTML anchors for object definitions in the formatted specification.
    • 1179: Tweak the styling of <code> snippets in tables rendered from OpenAPI definitions.
    • 1185: Update “API Standards” section to clarify how JSON is used.

Application Service API

  • Breaking Changes

    • 1200: Replace homeserver authorization approach with an Authorization header instead of access_token when talking to the application service, as per MSC2832.

  • Spec Clarifications

    • 1174: Add HTML anchors for object definitions in the formatted specification.

Identity Service API

  • Spec Clarifications

    • 1174: Add HTML anchors for object definitions in the formatted specification.
    • 1185: Update “API Standards” section to clarify how JSON is used.

Push Gateway API

  • Spec Clarifications

    • 1174: Add HTML anchors for object definitions in the formatted specification.

Room Versions

  • Spec Clarifications

    • 1137: For room versions 1 through 10, clarify that events with rejected auth_events must be rejected.
    • 1158: For room versions 2–10: correct a mistaken clarification to the state resolution algorithm.
    • 1175: For room versions 7 through 10: Clarify that invite->knock is actually a legal transition.

Appendices

Internal Changes/Tooling

  • Backwards Compatible Changes

    • 1194: Add internal changes changelog section.

  • Spec Clarifications

    • 1191: Render HTML anchors for object definition tables.
    • 1195: Give rendered-data sections a background and some padding.
    • 1205: Fix rendering of shortcodes within the client-server API.
    • 1230: Fix the spacing of mapping types generated from the OpenAPI spec.

v1.3

Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.3
Release dateJune 15, 2022

Client-Server API

Deprecations

  • 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. (#1101)

Backwards Compatible Changes

  • 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. (#1002)
  • Add refresh tokens, per MSC2918. (#1056, #1113)
  • 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. (#1062)
  • Add support for a new knock_restricted join rule in supported room versions, as per MSC3787. (#1099)

Spec Clarifications

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

Server-Server API

Backwards Compatible Changes

  • Add a destination property to the Authorization header, as per MSC3383. (#1067)

Spec Clarifications

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

Application Service API

Backwards Compatible Changes

Identity Service API

No significant changes.

Push Gateway API

No significant changes.

Room Versions

Backwards Compatible Changes

  • Add room version 10 as per MSC3604. (#1099)
  • Enforce integer power levels in room version 10 as per MSC3667. (#1099)
  • Add a knock_restricted join rule supported by room version 10 as per MSC3787. (#1099)
  • Update the default room version to 9 as per MSC3589. (#3739)

Spec Clarifications

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

Appendices

No significant changes.

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.