POST /user_directory/search
(#1096)GET /rooms/{roomId}/event/{eventId}
(#1110)POST /delete_devices
(#1239)GET /thirdparty/*
Endpoints (#1353)POST /account/3pid/msisdn/requestToken
,POST /register/msisdn/requestToken
, andPOST /account/password/msisdn/requestToken
(#1507)POST /account/3pid/delete
(#1567)POST /rooms/{roomId}/read_markers
(#1635)
- Add more presence options to the
set_presence
parameter of/sync
. (Thanks @mujx!) (#780) - Add
token
parameter to the/keys/query
endpoint (#1104) - Add the room visibility options for the room directory (#1141)
- Add spec for ignoring users (#1142)
- Add the
/register/available
endpoint for username availability (#1151) - Add sticker messages (#1158)
- Specify how to control the power level required for
@room
(#1176) - Document
/logout/all
endpoint (#1263) - Add report content API (#1264)
- Add
allow_remote
to the content repo to avoid routing loops (#1265) - Document highlights field in /search response (#1274)
- End-to-end encryption for group chats:
- Olm and Megolm messaging algorithms.
m.room.encrypted
,m.room.encryption
,m.room_key
events.- Device verification process.
device_one_time_keys_count
sync parameter.device_lists:left
sync parameter. (#1284)
- Add
.well-known
server discovery method (#1359) - Document the GET version of
/login
(#1361) - Document the
server_name
parameter on/join/{roomIdOrAlias}
(#1364) - Document the CORS/preflight headers (#1365)
- Add new user identifier object for logging in (#1390)
- Document message formats on
m.text
andm.emote
messages (#1397) - Encrypt file attachments (#1420)
- Share room decryption keys between devices (#1465)
- Document and improve client interaction with pushers. (#1506)
- Add support for Room Versions. (#1516)
- Guests can now call /context and /event to fetch events (#1542)
- Add a common standard for user, room, and group mentions in messages. (#1547)
- Add server ACLs as an option for controlling federation in a room. (#1550)
- Add new push rules for encrypted events and
@room
notifications. (#1551) - Add third party network room directories, as provided by application services. (#1554)
- Document the
validated_at
andadded_at
fields onGET /acount/3pid
. (#1567) - Add an
inhibit_login
registration option. (#1589) - Recommend that servers set a Content Security Policy for the content repository. (#1600)
- Add "rich replies" - a way for users to better represent the conversation thread they are referencing in their messages. (#1617)
- Add support for read markers. (#1635)
- Mark
home_server
return field for/login
and/register
endpoints as deprecated (#1097) - Fix response format of
/keys/changes
endpoint (#1106) - Clarify default values for some fields on the
/search
API (#1109) - Fix the representation of
m.presence
events (#1137) - Clarify that
m.tag
ordering is done with numbers, not strings (#1139) - Clarify that
/account/whoami
should consider application services (#1152) - Update
ImageInfo
andThumbnailInfo
dimension schema descriptions to clarify that they relate to intended display size, as opposed to the intrinsic size of the image file. (#1158) - Mark
GET /rooms/{roomId}/members
as requiring authentication (#1245) - Clarify
changed
field behaviour in device tracking process (#1284) - Describe
StateEvent
for/createRoom
(#1329) - Describe how the
reason
is handled for kicks/bans (#1362) - Mark
GET /presence/{userId}/status
as requiring authentication (#1371) - Describe the rate limit error response schema (#1373)
- Clarify that clients must leave rooms before forgetting them (#1378)
- Document guest access in
/createRoom
presets (#1379) - Define what a
RoomEvent
is on/rooms/{roomId}/messages
(#1380) - Clarify the request and result types on
/search
(#1381) - Clarify some of the properties on the search result (#1400)
- Clarify how access tokens are meant to be supplied to the homeserver. (#1517)
- Document additional parameters on the
/createRoom
API. (#1518) - Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match. (#1551)
- Update all event examples to be accurate representations of their associated events. (#1558)
- Clarify the supported HTML features for room messages. (#1562)
- Move the
invite_room_state
definition underunsigned
where it actually resides. (#1568) - Clarify the homeserver's behaviour for searching users. (#1569)
- Clarify the object structures and defaults for Filters. (#1570)
- Clarify instances of
type: number
in the swagger/OpenAPI schema definitions. (#1571) - Clarify that left rooms also have account data in
/sync
. (#1572) - Clarify the event fields used in the
/sync
response. (#1573) - Fix naming of the body field in
PUT /directory/room
. (#1574) - Clarify the filter object schema used in room searching. (#1577)
- Document the 403 error for sending state events. (#1590)
- specify how to handle multiple olm sessions with the same device (#1596)
- Add the other keys that redactions are expected to preserve. (#1602)
- Clarify that clients should not be generating invalid HTML for formatted events. (#1605)
- Clarify the room tag structure (thanks @KitsuneRal!) (#1606)
- Add a note that clients may use the transaction ID to avoid flickering when doing local echo. (#1619)
- Include the request and response structures for the various
/requestToken
endpoints. (#1636) - Clarify the available error codes, and when to prefer the HTTP status code over the
errcode
. (#1637) - Clarify and generalise the language used for describing pagination. (#1642)
- Breaking changes:
- Change the rule kind of
.m.rule.contains_display_name
fromunderride
tooverride
. This works with all known clients which support push rules, but any other clients implementing the push rules API should be aware of this change. This makes it simple to mute rooms correctly in the API (#373). - Remove
/tokenrefresh
from the API (#395). - Remove requirement that tokens used in token-based login be macaroons (#395).
- Move
thumbnail_url
andthumbnail_info
members of json objects form.room.message
events with msgtypesm.image
,m.file
andm.location
, inside theinfo
member, to matchm.video
events (#723).
- Change the rule kind of
- Changes to the API which will be backwards-compatible for clients:
- Add
filename
parameter toPOST /_matrix/media/r0/upload
(#364). - Document CAS-based client login and the use of
m.login.token
in/login
(#367). - Make
origin_server_ts
a mandatory field of room events (#379). - Add top-level
account_data
key to the responses toGET /sync
andGET /initialSync
(#380). - Add
is_direct
flag toPOST /createRoom
and invite member event. Add 'Direct Messaging' module (#389). - Add
contains_url
option toRoomEventFilter
(#390). - Add
filter
optional query param to/messages
(#390). - Add 'Send-to-Device messaging' module (#386).
- Add 'Device management' module (#402).
- Require that User-Interactive auth fallback pages call
window.postMessage
to notify apps of completion (#398). - Add pagination and filter support to
/publicRooms
. Change response to omit fields rather than returnnull
. Add estimate of total number of rooms in list. (#388). - Allow guest accounts to use a number of endpoints which are required for end-to-end encryption. (#751).
- Add key distribution APIs, for use with end-to-end encryption. (#894).
- Add
m.room.pinned_events
state event for rooms. (#1007). - Add mention of ability to send Access Token via an Authorization Header.
- Add
guest_can_join
parameter toPOST /createRoom
(#1093). - New endpoints:
- Add
- Spec clarifications:
- Add endpoints and logic for invites and third-party invites to the federation spec and update the JSON of the request sent by the identity server upon 3PID binding (#997)
- Fix "membership" property on third-party invite upgrade example (#995)
- Fix response format and 404 example for room alias lookup (#960)
- Fix examples of
m.room.member
event and room state change, and added a clarification on the membership event sent upon profile update (#950). - Spell out the way that state is handled by
POST /createRoom
(#362). - Clarify the fields which are applicable to different types of push rule (#365).
- A number of clarifications to authentication (#371).
- Correct references to
user_id
which should have beensender
(#376). - Correct inconsistent specification of
redacted_because
fields and their values (#378). - Mark required fields in response objects as such (#394).
- Make
m.notice
description a bit harder in its phrasing to try to dissuade the same issues that occurred with IRC (#750). GET /user/{userId}/filter/{filterId}
requires authentication (#1003).- Add some clarifying notes on the behaviour of rooms with no
m.room.power_levels
event (#1026). - Clarify the relationship between
username
anduser_id
in the/register
API (#1032). - Clarify rate limiting and security for content repository. (#1064).
- Spec clarifications:
- Room aliases (#337):
- Make it clear that
GET /directory/room/{roomAlias}
must work for federated aliases. GET /directory/room/{roomAlias}
cannot return a 409; thePUT
endpoint can, however.
- Make it clear that
- Power levels:
- Clarify the room naming algorithm in certain edge cases (#351).
- Remove outdated references to the pre-r0
/events
API, and clarify the section on syncing (#352).
- Room aliases (#337):
- Changes to the API which will be backwards-compatible for clients:
- New endpoints:
- Updates to the Presence module
(#278,
#342):
- Remove unused
free_for_chat
presence state - Add
currently_active
flag to them.presence
event and theGET /presence/{userId}/status
response. - Make idle timeout the responsibility of the server
- Remove requirements on servers to propagate profile information via
m.presence
events.
- Remove unused
- Add new predefined push rules (#274, #340).
/sync
should always return aprev_batch
token (#345).- add
to
parameter toGET /rooms/{roomId}/messages
API (#348).
This release includes the following changes since r0.0.1:
Breaking changes to the API [1]:
POST /rooms/{roomId}/join
no longer permits use of a room alias instead of a room id. (POST /join/{roomIdOrAlias}
continues to allow either.)POST /account/3pid
: correct the name of thethree_pid_creds
parameterThe "Push Rules" module no longer supports device-specific rules:
GET /pushrules
no longer returns adevice
propertydevice/{profile_tag}
is no longer a validscope
for push rulesprofile_tag
is no longer a valid kind of condition on push rules.
(Device-specific push rules will be reintroduced in the future; in the meantime, their specification has been moved to a draft branch.)
Changes to the API which will be backwards-compatible for clients:
- New endpoints:
POST /logout
POST /rooms/{roomId}/unban
POST /rooms/{roomId}/kick
GET /pushers
GET /pushrules/{scope}/{kind}/{ruleId}/enabled
(previouslyPUT
-only)GET
andPUT /pushrules/{scope}/{kind}/{ruleId}/actions
- Add
third_party_signed
parameter toPOST /rooms/{roomId}/join
- Add
M_INVALID_USERNAME
as valid response toPOST /register
- Add
unread_notifications
field toGET /sync
response - Add optional
invite
property tom.room.power_levels
state event - Add optional
public_key
andpublic_keys
tom.room.third_party_invite
state event - Password-based
/login
may now use a third-party identifier instead of a matrix user id.
- New endpoints:
Spec clarifications
- Make the state diagram for room membership explicit
- Note that a user may not be invited to a room while banned
- Clarify the expected order of events in the response to
GET /rooms/{roomId}/context/{eventId}
, as well as correcting the example for that API - Clarify the behaviour of the "Room History Visibility" module; in
particular, the behaviour of the
shared
history visibilty, and how events at visibility boundaries should be handled - Separate the "Room Previews" module from "Guest access"
- Reword the description of the
profile_tag
property inPUT /pushers/set
, and note that it is not mandatory.
[1] | Our versioning policy would strictly require that a breaking change be denoted by a new major specification version. However we are not aware of any clients which rely on the old behaviour here, nor server implementations which offer it, so we have chosen to retain the r0 designation on this occasion. |
This release includes the following changes since r0.0.0:
API changes: - Added new
/versions
API -/createRoom
takes an optionalinvite_3pid
parameter -/publicRooms
returns anavatar_url
resultThe following APIs are now deprecated: -
/initialSync
-/events
-/events/:eventId
-/rooms/:roomId/initialSync
Spec clarifications - Document inter-version compatibility - Document the parameters to the
/user/:userId/filter
API - Document thenext_batch
parameter on/search
- Document the membership states onm.room.member
events - Minor clarifications/corrections to:- Guest access module
- Search module
/login
API/rooms/:roomId/send/:eventType/:txnId
API/rooms/:roomId/context/:eventId
API
This is the first release of the client-server specification. It is largely a dump of what has currently been implemented, and there are several inconsistencies.
An upcoming minor release will deprecate many of these inconsistencies, and they will be removed in the next major release.
Since the draft stage, the following major changes have been made: - /api/v1 and /v2_alpha path segments have been replaced with the major version of the release (i.e. 'r0'). - Some POST versions of APIs with both POST and PUT have been removed. - The specification has been split into one specification per API. This is the client-server API. The server-server API can be found documented separately. - All APIs are now documented using Swagger - The following modules have been added:
- Content repository
- Instant messaging
- Push notification
- History visibility
- Search
- Invites based on third party identifiers
- Room tagging
- Guest access
- Client config
- The following APIs were added:
-
/sync
-/publicRooms
-/rooms/{roomId}/forget
-/admin/whois
-/rooms/{roomId}/redact
-/user/{userId}/filter
- The following APIs have been significantly modified:
- Invitations now contain partial room state
- Invitations can now be rejected
-
/directory
- The following events have been added:
-
m.room.avatar
- Example signed json is included for reference
- Commentary on display name calculation was added