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

Changelog

This is version v1.8 of the Matrix specification.

v1.8

Git commit	https://github.com/matrix-org/matrix-spec/tree/v1.8
Release date	August 23, 2023

Client-Server API

Backwards Compatible Changes

Require callers to be joined to the room to report its events, as per MSC2249. (#1517)

Spec Clarifications

Fix missing type property in the JSON schema definition of the m.reaction event. Contributed by @chebureki. (#1552)
Make sure examples types match schema in definitions. (#1563)
Allow null in room_types in POST /publicRooms endpoints schemas. (#1564)
Fix broken header formatting. Contributed by @midnightveil. (#1578)
Render binary request and response bodies. (#1579)
Fix description of MAC calculation in SAS verification. (#1590)
Update link to SAS emoji definition data. (#1593)
Fix various typos throughout the specification. (#1597)

Server-Server API

Deprecations

Deprecate matrix SRV lookup steps during server discovery, as per MSC4040. (#1624)

Backwards Compatible Changes

Add matrix-fed SRV lookup steps to server discovery, as per MSC4040. (#1624)

Spec Clarifications

Document why /state_ids can respond with a 404. (#1521)
Fix response definition for POST /_matrix/federation/v1/user/keys/claim. (#1559)
Fix examples in server keys definition. (#1560)
Make sure examples types match schema in definitions. (#1563)
Allow null in room_types in POST /publicRooms endpoints schemas. (#1564)
Fix broken header formatting. Contributed by @midnightveil. (#1578)
Remove spurious mention of a “default port” with respect to SRV record lookup. (#1615)
Switch to ordered list for server name resolution steps. (#1623)

Application Service API

Spec Clarifications

Fix type of custom fields in thirdparty lookup queries. (#1584)

Identity Service API

Spec Clarifications

Make sure examples types match schema in definitions. (#1563)

Push Gateway API

No significant changes.

Room Versions

Backwards Compatible Changes

Add room version 11 as per MSC3820. (#1604)
Move redacts from top level to content on m.room.redaction events in room version 11, as per MSC2174. (#1604)
Remove creator from m.room.creator events in room version 11, as per MSC2175. (#1604)
Remove remaining usage of origin from events in room version 11, as per MSC3989. (#1604)
Update the redaction rules in room version 11, as per MSC2176 and MSC3821. (#1604)

Appendices

Backwards Compatible Changes

Allow + in Matrix IDs, as per MSC4009. (#1583)

Spec Clarifications

Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. (#1573)

Internal Changes/Tooling

Backwards Compatible Changes

Upgrade Swagger data to OpenAPI 3.1. (#1310)
Create @matrix-org/spec npm package to ship the SAS Emoji data definitions & translations. (#1620)

Spec Clarifications

Update the CI to validate the file extension of changelog entries. (#1542)
Disclosure sections now only display their title when collapsed. (#1549)
Fix the sidebar in recent versions of Hugo. (#1551)
Bump jsonschema to validate JSON Schemas against Draft 2020-12. (#1556)
Use Redocly CLI to validate OpenAPI definitions. (#1558)
Use tag name as the OpenAPI definition version. (#1561)
Make sure version in x-changedInMatrixVersion is a string. (#1562)
Clarify usage of ABNF for grammar in the documentation style guide. (#1582)
Remove unnecessary oneOfs in JSON schemas. (#1585)
Update the version of Hugo used to render the spec to v0.113.0. (#1591)
Fix rendered changelog with new version of towncrier. (#1598)
Improve the layout of tables on desktop displays. Contributed by Martin Fischer. (#1601)

v1.7

Git commit	https://github.com/matrix-org/matrix-spec/tree/v1.7
Release date	May 25, 2023

Client-Server API

New Endpoints

Backwards Compatible Changes

Changes to the server-side aggregation of m.replace (edit) events, as per MSC3925. (#1440, #1525)
Add new push rule conditions event_property_is and event_property_contains, as per MSC3758 and MSC3966. (#1464)
Add m.annotation relations (reactions), as per MSC2677. (#1475, #1531)
Support asynchronous media uploads, as per MSC2246. (#1499, #1510)
Document the m.mentions property; the .m.rule.is_user_mention and .m.rule.is_room_mention push rules; and other notification behaviour, as per MSC3952. (#1508)
Improve VoIP signaling, as per MSC2746. (#1511, #1540)
Update the scope of transaction IDs, as per MSC3970. (#1526)
Add an ability to redirect media downloads, as per MSC3860. (#1529)
Add an ability to use an existing session to log in another, as per MSC3882. (#1530)

Spec Clarifications

Clarify the sections of the specification concerning aggregation of child events. (#1424)
Fix various typos throughout the specification. (#1432, #1442, #1447, #1455, #1465, #1500, #1509)
Clarify that reply chain fallback for threads might not be present. (#1439)
Clarify what event property the content-specific push rules match against. (#1441)
Clarify the semantics that make requests idempotent. (#1449)
Improve documentation of how clients use push rules. (#1461)
Clarify that servers should enforce a default limit on a filter if one is not specified. (#1463)
Disambiguate using property names with dots in them during push rule processing, as per MSC3873 and MSC3980. (#1464)
Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. (#1474)
Remove outdated text saying that state_default is 0 if there is no m.room.power_levels event in a room. (#1479)
Remove fictitious token parameter on /keys/query endpoint. (#1485)
Fix rendering of properties with a list of types. (#1487)
Clarify parts of the cross-signing signature upload request. (#1495)
Remove the dont_notify and coalesce push rule actions, as per MSC3987. (#1501)
Clarify m.location scheme by partially reverting f1f32d3. Contributed by @HarHarLinks. (#1507)
Add missing knock_restricted join rule to the m.room.join_rules schema. (#1535)

Server-Server API

Spec Clarifications

Fix various typos throughout the specification. (#1431, #1447, #1466, #1518)
Fix PDU examples by removing invalid OpenAPI reference to examples/minimal_pdu.json. (#1454)
Remove leftover {key_id} from /_matrix/key/v2/server/. (#1473)
Remove extraneous age_ts field from the reference hash calculation section. (#1536)

Application Service API

New Endpoints

Backwards Compatible Changes

Add homeserver->appservice ping mechanism, as per MSC2659. Contributed by @tulir at @beeper. (#1516, #1541)

Spec Clarifications

Fix various typos throughout the specification. (#1447)

Identity Service API

Spec Clarifications

Corrections to the response format of /_matrix/identity/v2/store-invite. (#1486)

Push Gateway API

No significant changes.

Room Versions

Spec Clarifications

Clarifications of event ID formats in early room versions (#1484)

Appendices

Spec Clarifications

Clarify that the term “Canonical JSON” is a specific thing within the Matrix specification. (#1468)
Remove references to groups. (#1483)
Clarifications of event ID formats in early room versions. (#1484)

Internal Changes/Tooling

Spec Clarifications

Update references to Inter font. (#1444)
Endpoint disclosures now hide everything but the URL. (#1446)
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. (#1457)
Minor cleanups to the GitHub Actions workflows (#1476)
Fix generation of anchors for additional properties. (#1488)
Fix various typos throughout the specification. (#1534)
Document more of the spec release timeline/process. (#1538)

v1.6

Git commit	https://github.com/matrix-org/matrix-spec/tree/v1.6
Release date	February 14, 2023

Client-Server API

Backwards Compatible Changes

Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)
Add /rooms/<roomID>/timestamp_to_event endpoint, as per MSC3030. (#1366)
Define hkdf-hmac-sha256.v2 MAC method for SAS verification, as per MSC3783. (#1412)

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)
Clarify which events will be included in Stripped State. Contributed by @andybalaam. (#1409)
Add links to the spec for the definition of 3PID medium. (#1417)
Correct the order of the default override pushrules in the spec. (#1421)
Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. (#1433)

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, as per MSC3743. (#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)
Note that /_matrix/federation/v2/send_join should include heroes for nameless rooms, even when allowed to omit membership events, per MSC3943. (#1425)

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, as per MSC3743. (#1347)

Identity Service API

Backwards Compatible Changes

Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)

Push Gateway API

Backwards Compatible Changes

Add information on standard error responses for unknown endpoints/methods, as per MSC3743. (#1347)

Room Versions

Backwards Compatible Changes

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

Spec Clarifications

Clarify the grammar for room versions. (#1422)
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 <content> 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 commit	https://github.com/matrix-org/matrix-spec/tree/v1.5
Release date	November 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

Update docsy theme to v0.5.0 + matrix.org modifications (https://github.com/matrix-org/docsy/commit/a0032f8db919a6c67ba6cdef2c455f105b6272a2). (#1295)

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 commit	https://github.com/matrix-org/matrix-spec/tree/v1.4
Release date	September 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

Add per-thread notifications and read receipts, as per MSC3771 and MSC3773. (#1255)

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 commit	https://github.com/matrix-org/matrix-spec/tree/v1.3
Release date	June 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

Add timestamp massaging as per MSC3316. (#1094)

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 commit	https://github.com/matrix-org/matrix-doc/tree/v1.2
Release date	February 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

Add support for restricted rooms as per MSC3083, MSC3289, and MSC3375. (#3387)

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

Add Room Version 8 as per MSC3289. (#3387)
Add Room Version 9 as per MSC3375. (#3387)

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 commit	https://github.com/matrix-org/matrix-doc/tree/v1.1
Release date	November 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.

Client-Server API
- r0.6.1
- r0.6.0
- r0.5.0
- r0.4.0
- r0.3.0
- r0.2.0
- r0.1.0
- r0.0.1
- r0.0.0
- Legacy: The last draft before the spec was formally released in version r0.0.0.
Server-Server API
- r0.1.4
- r0.1.3
- r0.1.2
- r0.1.1
- r0.1.0
Application Service API
- r0.1.1
- r0.1.0
Identity Service API
- r0.3.0
- r0.2.1
- r0.2.0
- r0.1.0
Push Gateway API
- r0.1.0