You're looking at an unstable version of this specification. Unstable specifications may change at any time without notice.
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
- Spec Clarifications
- 1003: Adjust the OpenAPI specification so that the type
Flow information
is explicitly defined when the CS spec is rendered. - 1021: Correct the default value for
invite
where it is not specified in anm.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. - 3681: Fix broken syntax in Server Access Control Lists definition.
- 3690: Clarify the behaviour of
event_match
in push rule conditions. - 3711: Fix incorrectly referenced
m.login.appservice
login identifier, instead usingm.login.application_service
. - 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.
- 1003: Adjust the OpenAPI specification so that the type
Server-Server API
- Spec Clarifications
- 1032: Update various links which pointed to the old
matrix-doc
github repository. - 1038: Fix origin server name in S2S Request Authentication example.
- 3703: Correct misleading text for
/send_join
response. - 998: Remove
origin
field from PDUs which exists on many but not all PDUs in practice and doesn’t serve an actual purpose.
- 1032: Update various links which pointed to the old
Application Service API
Identity Service API
Push Gateway API
Room Versions
- Spec Clarifications
- 1037: Improve readability of definitions in the state resolution v2 algorithm.
Appendices
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 theunsigned
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 am.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
, andm.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 withKeyDescription
in markingname
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 clientwell_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
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 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
andm.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
andPOST /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
andm.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
andscore
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 ofr0
as per MSC2844. (#3421)
Spec Clarifications
- Fix issues with
age
andunsigned
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
title
s. (#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 inPUT /_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 inm.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
fromEncryptedFile
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
Backwards Compatible Changes
- Add cross-signing information to
GET /user/keys
andGET /user/devices/{userId}
,m.device_list_update
EDU, and a newm.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
Removed Endpoints
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
-
Server-Server API
-
Application Service API
-
Identity Service API
-
Push Gateway API