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

Backwards Compatible Changes

  • Add information on standard error responses for unknown endpoints/methods. (#1347)
  • Add /rooms/<roomID>/timestamp_to_event endpoint, as per MSC3030. (#1366)

Spec Clarifications

  • Clarify the power levels integer range. (#1169, #1355)
  • Clarify that /context always returns event even if limit is zero. Contributed by @sumnerevans at @beeper. (#1239)
  • Clarify what fields are required when deleting a pusher (#1321)
  • Improve the presentation of push rule kinds and actions. (#1348)
  • Add missing description to m.call.answer schema. (#1353)
  • Fix various typos throughout the specification. (#1363)
  • Clarify parts of the end-to-end encryption sections. (#1381)
  • Move login API definitions to the right heading. Contributed by @HarHarLinks. (#1382)
  • Add links to the spec for the definition of 3PID medium. (#1417)

Server-Server API

Breaking Changes

  • Remove keyId from the server /keys endpoints, as per MSC3938. (#1350)

Backwards Compatible Changes

  • Add information on standard error responses for unknown endpoints/methods. (#1347)
  • Add /timestamp_to_event/<roomID> endpoint, as per MSC3030. (#1366)
  • Extend /_matrix/federation/v2/send_join to allow omitting membership events, per MSC3706. (#1393, #1398)

Spec Clarifications

  • Include examples inline instead of using a reference for invite endpoint definitions. (#1349)
  • Fix POST _matrix/federation/v1/user/keys/claim response schema. (#1351)
  • Correct the default invite level definition in the “Checks performed on receipt of a PDU” section. (#1371)
  • Clarify that CNAMEs are permissible for server names. (#1376)
  • Fix edu_type in EDU examples. (#1383)

Application Service API

Backwards Compatible Changes

  • Add information on standard error responses for unknown endpoints/methods. (#1347)

Identity Service API

Backwards Compatible Changes

  • Add information on standard error responses for unknown endpoints/methods. (#1347)

Push Gateway API

Backwards Compatible Changes

  • Add information on standard error responses for unknown endpoints/methods. (#1347)

Room Versions

Backwards Compatible Changes

  • Update the default room version to 10, as per MSC3904. (#1397)

Spec Clarifications

  • Fix various typos throughout the specification. (#1423)

Appendices

No significant changes.

Internal Changes/Tooling

Spec Clarifications

  • Add link to the unstable spec to the README. (#1357)
  • Improve safety of the proposals retrieval script in the event of failure. (#1368)
  • Rename “” to “content” in the OpenAPI files for content uploads. (#1370)
  • Stop autogenerating examples where we already have an example. (#1384)
  • Improve formatting of definitions in the Push Notifications section. (#1415)

v1.5

Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.5
Release dateNovember 17, 2022

Client-Server API

Backwards Compatible Changes

  • Add m.reference relations, as per MSC3267. (#1206)
  • Add missing documentation for m.key.verification.request msgtype for in-room verification. (#1271)

Spec Clarifications

  • Fix various typos throughout the specification. (#1260, #1265, #1276)
  • Fix naming of device_one_time_keys_count in /sync. (#1266)
  • Improve display of event subtypes. (#1283)
  • Improve documentation about ephemeral events. (#1284)
  • Define a 400 response from /_matrix/client/v3/directory/rooms/{roomAlias}. (#1286)
  • Clarify parts of the end-to-end encryption sections. (#1294, #1345)
  • Various clarifications throughout the specification. (#1306)
  • Replace set_sound push rule action by set_tweak. (#1318)
  • Clarify the behavior of PUT /_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}. (#1319)
  • Clarify that .m.rule.master has a higher priority than any push rule. (#1320)
  • Require request field refresh_token at endpoint POST /_matrix/client/v3/refresh. (#1323)
  • Fix a number of broken links in the specification. (#1330)
  • Add example read receipt to GET /_matrix/client/v3/sync response example. (#1341)

Server-Server API

Spec Clarifications

  • Fix a number of broken links in the specification. (#1330)

Application Service API

Spec Clarifications

  • Clarify that application services can only register an interest in local users, as per MSC3905. (#1305)

Identity Service API

Spec Clarifications

  • Fix a number of broken links in the specification. (#1330)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

  • Reword the event auth rules to clarify that users cannot demote other users with the same power level. (#1269)
  • Various clarifications to the text on event authorisation rules. (#1270)
  • Fix a number of broken links in the specification. (#1330)

Appendices

No significant changes.

Internal Changes/Tooling

Backwards Compatible Changes

Spec Clarifications

  • Improve error messages emitted by resolve-additional-types template. (#1303)
  • Fix link to API viewer. (#1308)
  • Stop rendering the subsections of the Client-Server API and Room Versions specs as their own separate pages. (#1317)
  • Use a link checker to ensure that we do not have broken links. (#1329, #1338)
  • Update instructions to preview Swagger definitions. (#1331)
  • Make definition anchors more unique. (#1339)
  • Generate the unstable changelogs with towncrier, for consistency. (#1340)
  • Update CONTRIBUTING.md to mention that non-content changes to this repo should have an “internal” changelog entry. (#1342)
  • Update module summary table with new modules: Event Replacements, Threading and Reference Relations. (#1344)
  • Disable RSS generation for the spec. (#1346)

v1.4

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

Client-Server API

Removed Endpoints

  • Remove unused policy room sharing mechanism, as per MSC3844. (#1196)

Backwards Compatible Changes

  • Add a .m.rule.room.server_acl push rule to match m.room.server_acl events, as per MSC3786. (#1190, #1201)
  • Add Cross-Origin-Resource-Policy (CORP) headers to media repository, as per MSC3828. (#1197)
  • Copy a room’s type when upgrading it, as per MSC3818. (#1198)
  • Add room_types filter and room_type response to /publicRooms, as per MSC3827. (#1199)
  • Add m.replace relations (event edits), as per MSC2676. (#1211)
  • 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. (#1216)
  • Add threading via m.thread relations, as per MSC3440, MSC3816, MSC3856, and MSC3715. (#1254)
  • Add per-thread notifications and read receipts, as per MSC3771 and MSC3773. (#1255)
  • Add thread_id to the /receipt endpoint, as per MSC3771. (#1261)

Spec Clarifications

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

Server-Server API

Backwards Compatible Changes

Spec Clarifications

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

Application Service API

Breaking Changes

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

Spec Clarifications

  • Add HTML anchors for object definitions in the formatted specification. (#1174)

Identity Service API

Spec Clarifications

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

Push Gateway API

Spec Clarifications

  • Add HTML anchors for object definitions in the formatted specification. (#1174)

Room Versions

Spec Clarifications

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

Appendices

No significant changes.

Internal Changes/Tooling

Backwards Compatible Changes

  • Add internal changes changelog section. (#1194)

Spec Clarifications

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

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.