mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-19 20:43:42 +01:00
Compare commits
32 commits
339ea6be12
...
d05a26b24e
| Author | SHA1 | Date | |
|---|---|---|---|
|
d05a26b24e | ||
|
|
20828ee354 | ||
|
|
dd8aaa0d66 | ||
|
|
3946435d7f | ||
|
|
2c734c3c5b | ||
|
|
075d203ecd | ||
|
|
4ed55a60ec | ||
|
|
67743d5715 | ||
|
|
338047ec7b | ||
|
|
0439707624 | ||
|
|
f4e6e6dea9 | ||
|
|
73fcf366a0 | ||
|
|
0a1efd8c9c | ||
|
|
2c6ddafb43 | ||
|
|
fc81171081 | ||
|
|
c74befd111 | ||
|
|
ca9c376076 | ||
|
|
fe46e0c363 | ||
|
|
a8c326962a | ||
|
|
fca171427f | ||
|
|
81273df88e | ||
|
|
65b1db721d | ||
|
|
c39c7d0680 | ||
|
|
23ff7f1343 | ||
|
|
8a2c58b1b1 | ||
|
|
817ec5380f | ||
|
|
029be205b9 | ||
|
|
fe880fdaf4 | ||
|
|
71ce620fc0 | ||
|
|
cb6d039c57 | ||
|
|
c7581356bf | ||
|
|
7fd49a2808 |
16
.github/workflows/main.yml
vendored
16
.github/workflows/main.yml
vendored
|
|
@ -2,6 +2,7 @@ name: "Spec"
|
|||
|
||||
env:
|
||||
HUGO_VERSION: 0.139.0
|
||||
PYTHON_VERSION: 3.13
|
||||
|
||||
on:
|
||||
push:
|
||||
|
|
@ -40,7 +41,7 @@ jobs:
|
|||
- name: "➕ Setup Python"
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.9'
|
||||
python-version: ${{ env.PYTHON_VERSION }}
|
||||
cache: 'pip'
|
||||
cache-dependency-path: scripts/requirements.txt
|
||||
- name: "➕ Install dependencies"
|
||||
|
|
@ -59,7 +60,7 @@ jobs:
|
|||
- name: "➕ Setup Python"
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.9'
|
||||
python-version: ${{ env.PYTHON_VERSION }}
|
||||
cache: 'pip'
|
||||
cache-dependency-path: scripts/requirements.txt
|
||||
- name: "➕ Install dependencies"
|
||||
|
|
@ -78,7 +79,7 @@ jobs:
|
|||
- name: "➕ Setup Python"
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.9'
|
||||
python-version: ${{ env.PYTHON_VERSION }}
|
||||
cache: 'pip'
|
||||
cache-dependency-path: scripts/requirements.txt
|
||||
- name: "➕ Install dependencies"
|
||||
|
|
@ -120,7 +121,7 @@ jobs:
|
|||
- name: "➕ Setup Python"
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.9'
|
||||
python-version: ${{ env.PYTHON_VERSION }}
|
||||
cache: 'pip'
|
||||
cache-dependency-path: scripts/requirements.txt
|
||||
- name: "➕ Install dependencies"
|
||||
|
|
@ -172,7 +173,7 @@ jobs:
|
|||
- name: "➕ Setup Python"
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.9'
|
||||
python-version: ${{ env.PYTHON_VERSION }}
|
||||
- name: "➕ Install towncrier"
|
||||
run: "pip install 'towncrier'"
|
||||
- name: "Generate changelog"
|
||||
|
|
@ -283,10 +284,11 @@ jobs:
|
|||
npm i
|
||||
npm run get-proposals
|
||||
- name: "⚙️ hugo"
|
||||
env:
|
||||
HUGO_PARAMS_VERSION_STATUS: "historical"
|
||||
# Create a baseURL like `/v1.2` out of the `v1.2` tag
|
||||
run: |
|
||||
echo -e '[params.version]\nstatus="historical"' > historical.toml
|
||||
hugo --config config.toml,historical.toml --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
|
||||
hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
|
||||
|
||||
- name: "📥 Spec definition download"
|
||||
uses: actions/download-artifact@v4
|
||||
|
|
|
|||
|
|
@ -316,13 +316,19 @@ Custom SCSS for the Matrix spec
|
|||
h2 {
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.3rem;
|
||||
margin: 3rem 0 .5rem 0;
|
||||
margin: 1.5rem 0 1rem 0;
|
||||
}
|
||||
|
||||
h3 {
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.1rem;
|
||||
margin: 1.5rem 0 .75rem 0;
|
||||
margin: 1.5rem 0 1rem 0;
|
||||
|
||||
}
|
||||
|
||||
/* Reduce top margin of h3 if previous sibling is a h2 */
|
||||
h2 + h3 {
|
||||
margin-top: 1rem;
|
||||
}
|
||||
|
||||
hr {
|
||||
|
|
@ -367,11 +373,6 @@ Custom SCSS for the Matrix spec
|
|||
}
|
||||
}
|
||||
|
||||
// add some space between two tables when they are right next to each other
|
||||
& + table {
|
||||
margin-top: 4rem;
|
||||
}
|
||||
|
||||
caption {
|
||||
caption-side: top;
|
||||
color: $dark;
|
||||
|
|
@ -443,6 +444,17 @@ Custom SCSS for the Matrix spec
|
|||
}
|
||||
}
|
||||
|
||||
/* Have consistent spacing around tables and examples */
|
||||
table, .highlight {
|
||||
margin-top: 0;
|
||||
margin-bottom: 2rem;
|
||||
|
||||
/* We don't need the margin on the last child of the .rendered-data block */
|
||||
&:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
}
|
||||
|
||||
pre {
|
||||
border: 0;
|
||||
border-left: solid 5px $secondary;
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Correct null value handling for the AS Registration's `url` property.
|
||||
|
|
@ -1 +0,0 @@
|
|||
The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Document the `instance_id` field of `Protocol Instance` in the responses to
|
||||
`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Applying redactions is a SHOULD for clients.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify which rooms are returned from `/hierarchy`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clients can choose which history visibility options they offer to users when creating rooms.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Clarify the format of third-party invites, including the fact that identity
|
||||
server public keys can be encoded using standard or URL-safe base64.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
1
changelogs/client_server/newsfragments/2095.feature
Normal file
1
changelogs/client_server/newsfragments/2095.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms in profile look-ups are defined through their join rule and history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms in user directory queries are defined through their join rule and history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms with respect to call invites are defined through their join rule.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms have no specific meaning with respect to moderation policy lists.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"Public" rooms with respect to presence are defined through their join rule.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix typo: as->has.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that public keys can be encoded using standard or URL-safe base64.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Generate the changelog release info with Hugo, rather than the changelog generation script.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update release steps documentation.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove unused `release_date` from Hugo config.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that v1.0 of Matrix was a release prior to the current global versioning system.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix the version of the Identity Service API when Matrix 1.0 was introduced.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Deduplicate the definition of `RoomKeysUpdateResponse`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Deduplicate the definitions of `Invite3pid`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Support more locations for examples in OpenAPI definitions and JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add link to the git commit for the unstable changelog.
|
||||
1
changelogs/internal/newsfragments/2081.clarification
Normal file
1
changelogs/internal/newsfragments/2081.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Adjust margins in rendered endpoints.
|
||||
1
changelogs/internal/newsfragments/2088.clarification
Normal file
1
changelogs/internal/newsfragments/2088.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Replace Hugo shortcodes in OpenAPI output.
|
||||
1
changelogs/internal/newsfragments/2115.clarification
Normal file
1
changelogs/internal/newsfragments/2115.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.
|
||||
1
changelogs/internal/newsfragments/2123.clarification
Normal file
1
changelogs/internal/newsfragments/2123.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Fix the historical info box when generating the historical spec in CI.
|
||||
|
|
@ -1 +0,0 @@
|
|||
For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Refactor PDU definitions to reduce duplication.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove an erroneous `room_id` field in a few examples.
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Clarify the format of third-party invites, including the fact that identity
|
||||
server public keys can be encoded using standard or URL-safe base64.
|
||||
1
changelogs/server_server/newsfragments/2095.feature
Normal file
1
changelogs/server_server/newsfragments/2095.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.
|
||||
|
|
@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
|
|||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
# major = "1"
|
||||
# minor = "13"
|
||||
# minor = "14"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
|
|||
|
|
@ -492,10 +492,10 @@ via the query string). It is expected that the application service use
|
|||
the transactions pushed to it to handle events rather than syncing with
|
||||
the user implied by `sender_localpart`.
|
||||
|
||||
#### Application service room directories
|
||||
#### Published room directories
|
||||
|
||||
Application services can maintain their own room directories for their
|
||||
defined third-party protocols. These room directories may be accessed by
|
||||
Application services can maintain their own published room directories for
|
||||
their defined third-party protocols. These directories may be accessed by
|
||||
clients through additional parameters on the `/publicRooms`
|
||||
client-server endpoint.
|
||||
|
||||
|
|
|
|||
93
content/changelog/v1.14.md
Normal file
93
content/changelog/v1.14.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
title: v1.14 Changelog
|
||||
linkTitle: v1.14
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2025-03-27
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**New Endpoints**
|
||||
|
||||
- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
|
||||
- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
|
||||
- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
|
||||
- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
|
||||
- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
|
||||
- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
|
||||
- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
|
||||
- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
|
||||
- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
|
||||
- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
|
||||
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
|
||||
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
|
||||
- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
|
||||
- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
|
||||
- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
|
||||
- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
|
||||
- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
|
||||
- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
|
||||
- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
|
||||
- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
|
||||
- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
|
||||
- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))
|
||||
|
|
@ -371,15 +371,23 @@ valid data was obtained, but no server is available to serve the client.
|
|||
No further guess should be attempted and the user should make a
|
||||
conscientious decision what to do next.
|
||||
|
||||
### Well-known URI
|
||||
### Well-known URIs
|
||||
|
||||
Matrix facilitates automatic discovery for the Client-Server API base URL and more via the
|
||||
[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) "Well-Known URI" method.
|
||||
This method uses JSON files at a predetermined location on the root path `/.well-known/` to
|
||||
specify parameter values.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Diverging from the rest of the endpoints in the Client-Server spec, these files can not be provided
|
||||
on the base URL that the Client-Server API is reachable on, as it is yet to be discovered.
|
||||
Instead, they can be reached via HTTPS on the [server name](/appendices/#server-name)'s hostname as domain.
|
||||
|
||||
Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
|
||||
as per the [CORS](#web-browser-clients) section in this specification.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
The `.well-known` method uses a JSON file at a predetermined location to
|
||||
specify parameter values. The flow for this method is as follows:
|
||||
The flow for auto-discovery is as follows:
|
||||
|
||||
1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
|
||||
Matrix ID at the first colon.
|
||||
|
|
@ -415,10 +423,17 @@ specify parameter values. The flow for this method is as follows:
|
|||
|
||||
{{% http-api spec="client-server" api="wellknown" %}}
|
||||
|
||||
{{% http-api spec="client-server" api="versions" %}}
|
||||
|
||||
{{% http-api spec="client-server" api="support" %}}
|
||||
|
||||
### API Versions
|
||||
|
||||
Upon connecting, the Matrix client and server need to negotiate which version of the specification
|
||||
they commonly support, as the API evolves over time. The server advertises its supported versions
|
||||
and optionally unstable features to the client, which can then go on to make requests to the
|
||||
endpoints it supports.
|
||||
|
||||
{{% http-api spec="client-server" api="versions" %}}
|
||||
|
||||
## Client Authentication
|
||||
|
||||
Most API endpoints require the user to identify themselves by presenting
|
||||
|
|
@ -2831,7 +2846,35 @@ re-invited.
|
|||
|
||||
{{% http-api spec="client-server" api="banning" %}}
|
||||
|
||||
### Listing rooms
|
||||
### Published room directory
|
||||
|
||||
Homeservers MAY publish a room directory to allow users to discover rooms. A room
|
||||
can have one of two visibility settings in the directory:
|
||||
|
||||
- `public`: The room will be shown in the published room directory.
|
||||
- `private`: The room will be hidden from the published room directory.
|
||||
|
||||
Clients can define a room's initial visibility in the directory via the `visibility`
|
||||
parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room
|
||||
creation, clients can query and change a room's visibility in the directory through
|
||||
the endpoints listed below, provided that the server permits this.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
The visibility setting merely defines whether a room is included in the published
|
||||
room directory or not. It doesn't make any guarantees about the room's
|
||||
[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility).
|
||||
|
||||
In particular, a visibility setting of `public` should not be confused with a `public`
|
||||
join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published
|
||||
in the directory, too.
|
||||
|
||||
Similarly, a visibility setting of `public` does not necessarily imply a `world_readable`
|
||||
history visibility.
|
||||
|
||||
To increase performance or by preference, servers MAY apply additional filters when listing the
|
||||
directory, for instance, by automatically excluding rooms with `invite` join rules
|
||||
that are not `world_readable` regardless of their visibility.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
{{% http-api spec="client-server" api="list_public_rooms" %}}
|
||||
|
||||
|
|
@ -2847,10 +2890,15 @@ re-invited.
|
|||
|
||||
#### Server behaviour
|
||||
|
||||
Homeservers MUST at a minimum allow profile look-up for:
|
||||
Homeservers MUST at a minimum allow profile look-up for users who are
|
||||
visible to the requester based on their membership in rooms known to the
|
||||
homeserver. This means:
|
||||
|
||||
- users that share a room with the requesting user
|
||||
- users that reside in public rooms known to the homeserver
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`public` [join rule](#mroomjoin_rules)
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`world_readable` [history visibility](#room-history-visibility)
|
||||
|
||||
In all other cases, homeservers MAY deny profile look-up by responding with
|
||||
403 and an error code of `M_FORBIDDEN`.
|
||||
|
|
|
|||
|
|
@ -528,7 +528,7 @@ messages, Alice only sends one request event (an event with type
|
|||
`m.room.message` with `msgtype: m.key.verification.request`, rather than an
|
||||
event with type `m.key.verification.request`), to the room. In addition, Alice
|
||||
does not send an `m.key.verification.cancel` event to tell Bob's other devices
|
||||
that the request as already been accepted; instead, when Bob's other devices
|
||||
that the request has already been accepted; instead, when Bob's other devices
|
||||
see his `m.key.verification.ready` event, they will know that the request has
|
||||
already been accepted, and that they should ignore the request.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,8 +18,9 @@ the entity making the decisions on filtering is best positioned to
|
|||
interpret the rules how it sees fit.
|
||||
|
||||
Moderation policy lists are stored as room state events. There are no
|
||||
restrictions on how the rooms can be configured (they could be public,
|
||||
private, encrypted, etc).
|
||||
restrictions on how the rooms can be configured in terms of
|
||||
[join rules](#mroomjoin_rules), [history visibility](#room-history-visibility),
|
||||
encryption, etc.
|
||||
|
||||
There are currently 3 kinds of entities which can be affected by rules:
|
||||
`user`, `server`, and `room`. All 3 are described with
|
||||
|
|
|
|||
|
|
@ -68,5 +68,7 @@ will cause the server to automatically set their presence to `online`.
|
|||
|
||||
#### Security considerations
|
||||
|
||||
Presence information is shared with all users who share a room with the
|
||||
target user. In large public rooms this could be undesirable.
|
||||
Presence information is published to all users who share a room with the
|
||||
target user. If the target user is a member of a room with a `public`
|
||||
[join rule](#mroomjoin_rules), any other user in the federation is
|
||||
able to gain access to the target user's presence. This could be undesirable.
|
||||
|
|
|
|||
|
|
@ -29,3 +29,9 @@ is in before accepting a report.
|
|||
based on whether or not the reporting user is joined to the room. This is
|
||||
because users can be exposed to harmful content without being joined to a
|
||||
room. For instance, through room directories or invites.
|
||||
|
||||
{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
|
||||
based on whether or not the reporting user is joined to any rooms that the
|
||||
reported user is joined to. This is because users can be exposed to harmful
|
||||
content without being joined to a room. For instance, through user
|
||||
directories or invites.
|
||||
|
|
|
|||
|
|
@ -26,9 +26,10 @@ on certain keys of certain event types.
|
|||
|
||||
The supported keys to search over are:
|
||||
|
||||
- `content.body` in `m.room.message`
|
||||
- `content.name` in `m.room.name`
|
||||
- `content.topic` in `m.room.topic`
|
||||
- `content.body` in [`m.room.message`](/client-server-api/#mroommessage)
|
||||
- `content.name` in [`m.room.name`](/client-server-api/#mroomname)
|
||||
- In [`m.room.topic`](/client-server-api/#mroomtopic), `content.topic`
|
||||
as well as the `body` of the `text/plain` representation in `content['m.topic']`.
|
||||
|
||||
The search will *not* include rooms that are end to end encrypted.
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise,
|
|||
clients will try to use the default key to decrypt secrets.
|
||||
|
||||
Clients that want to present a simplified interface to users by not supporting
|
||||
multiple keys should use the default key if one is specified. If not default
|
||||
multiple keys should use the default key if one is specified. If no default
|
||||
key is specified, the client may behave as if there is no key is present at
|
||||
all. When such a client creates a key, it should mark that key as being the
|
||||
default key.
|
||||
|
|
|
|||
|
|
@ -18,10 +18,10 @@ In the default power level structure, this would be `100`. Clients might wish to
|
|||
go a step further and explicitly ignore notification counts on space-rooms.
|
||||
|
||||
Membership of a space is defined and controlled by the existing mechanisms which
|
||||
govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
|
||||
and [`m.room.join_rules`](#mroomjoin_rules). Canonical aliases and invites, including
|
||||
govern a room: [`m.room.member`](/client-server-api#mroommember), [`m.room.history_visibility`](/client-server-api#mroomhistory_visibility),
|
||||
and [`m.room.join_rules`](/client-server-api#mroomjoin_rules). Canonical aliases and invites, including
|
||||
third-party invites, still work just as they do in normal rooms as well. Furthermore,
|
||||
spaces can also be published in the [room directory](#room-directory) to make them
|
||||
spaces can also be published in the [room directory](/client-server-api#published-room-directory) to make them
|
||||
discoverable.
|
||||
|
||||
All other aspects of regular rooms are additionally carried over, such as the
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ This module adds in support for inviting new members to a room where
|
|||
their Matrix user ID is not known, instead addressing them by a third-party
|
||||
identifier such as an email address. There are two flows here; one
|
||||
if a Matrix user ID is known for the third-party identifier, and one if
|
||||
not. Either way, the client calls [`/invite`](#post_matrixclientv3roomsroomidinvite) with the details of the
|
||||
third-party identifier.
|
||||
not. Either way, the client calls [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite)
|
||||
with the details of the third-party identifier.
|
||||
|
||||
The homeserver asks the identity server whether a Matrix user ID is
|
||||
known for that identifier:
|
||||
|
|
@ -37,10 +37,12 @@ A client asks a server to invite a user by their third-party identifier.
|
|||
|
||||
#### Server behaviour
|
||||
|
||||
Upon receipt of an [`/invite`](#post_matrixclientv3roomsroomidinvite), the server is expected to look up the
|
||||
third-party identifier with the provided identity server. If the lookup
|
||||
yields a result for a Matrix User ID then the normal invite process can
|
||||
be initiated. This process ends up looking like this:
|
||||
Upon receipt of an [`/invite`](#thirdparty_post_matrixclientv3roomsroomidinvite),
|
||||
the server is expected to look up the third-party identifier with the provided
|
||||
identity server by making a call to [`/_matrix/identity/v2/lookup`](/identity-service-api/#post_matrixidentityv2lookup).
|
||||
If the lookup yields a result for a Matrix User ID then the normal [invite
|
||||
process](/server-server-api/#inviting-to-a-room) can be initiated. This process
|
||||
ends up looking like this:
|
||||
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -66,10 +68,11 @@ be initiated. This process ends up looking like this:
|
|||
| | |
|
||||
```
|
||||
|
||||
However, if the lookup does not yield a bound User ID, the homeserver
|
||||
must store the invite on the identity server and emit a valid
|
||||
`m.room.third_party_invite` event to the room. This process ends up
|
||||
looking like this:
|
||||
However, if the lookup does not yield a bound User ID, the homeserver must store
|
||||
the invite on the identity server with a call to
|
||||
[`/_matrix/identity/v2/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
|
||||
and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
|
||||
to the room. This process ends up looking like this:
|
||||
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -101,15 +104,18 @@ looking like this:
|
|||
| | |
|
||||
```
|
||||
|
||||
All homeservers MUST verify the signature in the event's
|
||||
`content.third_party_invite.signed` object.
|
||||
The third-party user will then need to verify their identity, which results in a
|
||||
request to [`/_matrix/federation/v1/3pid/onbind`](/server-server-api/#put_matrixfederationv13pidonbind)
|
||||
from the identity server to the homeserver that bound the third-party identifier
|
||||
to a user. The homeserver then exchanges the `m.room.third_party_invite` event
|
||||
in the room for a complete [`m.room.member`](#mroommember) event with
|
||||
`content.membership: invite` and a `content.third_party_invite` property for the
|
||||
user that has bound the third-party identifier. If the invitee is on a different
|
||||
homeserver than the inviting user, the invitee's homeserver makes a request to
|
||||
[`/_matrix/federation/v1/exchange_third_party_invite/{roomId}`](/server-server-api/#put_matrixfederationv1exchange_third_party_inviteroomid).
|
||||
|
||||
The third-party user will then need to verify their identity, which
|
||||
results in a call from the identity server to the homeserver that bound
|
||||
the third-party identifier to a user. The homeserver then exchanges the
|
||||
`m.room.third_party_invite` event in the room for a complete
|
||||
`m.room.member` event for `membership: invite` for the user that has
|
||||
bound the third-party identifier.
|
||||
All homeservers MUST verify the signature in the `m.room.member` event's
|
||||
`content.third_party_invite.signed` object.
|
||||
|
||||
If a homeserver is joining a room for the first time because of an
|
||||
`m.room.third_party_invite`, the server which is already participating
|
||||
|
|
@ -193,8 +199,8 @@ at any time - the completion is not shown in the diagram.
|
|||
|
||||
H1 MUST verify the request from H3 to ensure the `signed` property is
|
||||
correct as well as the `key_validity_url` as still being valid. This is
|
||||
done by making a request to the [identity server
|
||||
/isvalid](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
|
||||
done by making a request to the identity server's
|
||||
[`/pubkey/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyisvalid)
|
||||
endpoint, using the provided URL rather than constructing a new one. The
|
||||
query string and response for the provided URL must match the Identity
|
||||
Service Specification.
|
||||
|
|
|
|||
|
|
@ -202,11 +202,13 @@ specific user, and should be set to the Matrix user ID of that user. Invites
|
|||
without an `invitee` field are defined to be intended for any member of the
|
||||
room other than the sender of the event.
|
||||
|
||||
Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either
|
||||
absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their
|
||||
user's trust relationship with the callers and/or where the call was placed. As a starting point, it is
|
||||
suggested that clients ignore call invites from users in public rooms. It is strongly recommended that
|
||||
when clients do not ring for an incoming call invite, they still display the call invite in the room and
|
||||
Clients should consider an incoming call if they see a non-expired invite event
|
||||
where the `invitee` field is either absent or equal to their user's Matrix ID.
|
||||
They should, however, evaluate whether or not to ring based on their user's trust
|
||||
relationship with the callers and/or where the call was placed. As a starting
|
||||
point, it is RECOMMENDED that clients ignore call invites in rooms with a
|
||||
[join rule](#mroomjoin_rules) of `public`. When clients suppress ringing for an
|
||||
incoming call invite, they SHOULD still display the call invite in the room and
|
||||
annotate that it was ignored.
|
||||
|
||||
##### Glare
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including
|
|||
discovered security vulnerabilities and age.
|
||||
|
||||
Clients should not ask room administrators to upgrade their rooms if the
|
||||
room is running a stable version. Servers SHOULD use **room version 10** as
|
||||
room is running a stable version. Servers SHOULD use **room version 11** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
The available room versions are:
|
||||
|
|
|
|||
4
content/rooms/fragments/v6-event-format.md
Normal file
4
content/rooms/fragments/v6-event-format.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
|
||||
Events in rooms of this version have the following structure:
|
||||
|
||||
{{% definition path="api/server-server/definitions/pdu_v6" %}}
|
||||
|
|
@ -281,7 +281,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### State resolution
|
||||
|
||||
|
|
|
|||
|
|
@ -39,6 +39,13 @@ in [room version 5](/rooms/v5).
|
|||
|
||||
[See above](#redactions).
|
||||
|
||||
### Event format
|
||||
|
||||
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
|
||||
the `depth` limit has been reduced in this room version.
|
||||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=6 %}} Rule 4, which related specifically to events
|
||||
|
|
@ -229,10 +236,6 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v4-event-ids" %}}
|
||||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
{{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}
|
||||
|
|
|
|||
|
|
@ -225,7 +225,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -119,7 +119,8 @@ to send. The process overall is as follows:
|
|||
server must present a valid certificate for the hostname.
|
||||
|
||||
3. If the hostname is not an IP literal, a regular HTTPS request is
|
||||
made to `https://<hostname>/.well-known/matrix/server`, expecting
|
||||
made to `https://<hostname>/.well-known/matrix/server` (according to
|
||||
[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), expecting
|
||||
the schema defined later in this section. 30x redirects should be
|
||||
followed, however redirection loops should be avoided. Responses
|
||||
(successful or otherwise) to the `/.well-known` endpoint should be
|
||||
|
|
@ -543,8 +544,8 @@ the following subset of the room state:
|
|||
`third_party_invite` property, the current
|
||||
`m.room.third_party_invite` event with `state_key` matching
|
||||
`content.third_party_invite.signed.token`, if any.
|
||||
- If `content.join_authorised_via_users_server` is present,
|
||||
and the [room version supports restricted rooms](/rooms/#feature-matrix),
|
||||
- If `membership` is `join`, `content.join_authorised_via_users_server`
|
||||
is present, and the [room version supports restricted rooms](/rooms/#feature-matrix),
|
||||
then the `m.room.member` event with `state_key` matching
|
||||
`content.join_authorised_via_users_server`.
|
||||
|
||||
|
|
@ -970,9 +971,8 @@ the event to other servers in the room.
|
|||
## Third-party invites
|
||||
|
||||
{{% boxes/note %}}
|
||||
More information about third-party invites is available in the
|
||||
[Client-Server API](/client-server-api) under
|
||||
the Third-party Invites module.
|
||||
More information about third-party invites is available in the Client-Server API
|
||||
under the [Third-party invites](/client-server-api/#third-party-invites) module.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When a user wants to invite another user in a room but doesn't know the
|
||||
|
|
@ -985,38 +985,41 @@ API](/identity-service-api).
|
|||
|
||||
### Cases where an association exists for a third-party identifier
|
||||
|
||||
If the third-party identifier is already bound to a Matrix ID, a lookup
|
||||
request on the identity server will return it. The invite is then
|
||||
processed by the inviting homeserver as a standard `m.room.member`
|
||||
invite event. This is the simplest case.
|
||||
If the third-party identifier is already bound to a Matrix ID, a [lookup
|
||||
request](/identity-service-api/#post_matrixidentityv2lookup) on the identity
|
||||
server will return it. The invite is then processed by the inviting homeserver
|
||||
as a [standard `m.room.member` invite event](#inviting-to-a-room). This is the
|
||||
simplest case.
|
||||
|
||||
### Cases where an association doesn't exist for a third-party identifier
|
||||
|
||||
If the third-party identifier isn't bound to any Matrix ID, the inviting
|
||||
homeserver will request the identity server to store an invite for this
|
||||
identifier and to deliver it to whoever binds it to its Matrix ID. It
|
||||
will also send an `m.room.third_party_invite` event in the room to
|
||||
specify a display name, a token and public keys the identity server
|
||||
provided as a response to the invite storage request.
|
||||
homeserver will request the identity server to [store an invite](/identity-service-api/#invitation-storage)
|
||||
for this identifier and to deliver it to whoever binds it to its Matrix ID. It
|
||||
will also send an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
|
||||
event in the room to specify a display name, a token and public keys the
|
||||
identity server provided as a response to the invite storage request.
|
||||
|
||||
When a third-party identifier with pending invites gets bound to a
|
||||
Matrix ID, the identity server will send a POST request to the ID's
|
||||
homeserver as described in the [Invitation
|
||||
Storage](/identity-service-api#invitation-storage)
|
||||
section of the Identity Service API.
|
||||
When a third-party identifier with pending invites gets bound to a Matrix ID,
|
||||
the identity server will send a request to the [`/3pid/onbind`](#put_matrixfederationv13pidonbind)
|
||||
endpoint of the the ID's homeserver as described in the [Invitation
|
||||
Storage](/identity-service-api#invitation-storage) section of the Identity
|
||||
Service API.
|
||||
|
||||
The following process applies for each invite sent by the identity
|
||||
server:
|
||||
|
||||
The invited homeserver will create an `m.room.member` invite event
|
||||
containing a special `third_party_invite` section containing the token
|
||||
and a signed object, both provided by the identity server.
|
||||
The invited homeserver will create an [`m.room.member`](/client-server-api/#mroommember)
|
||||
invite event containing a special `third_party_invite` section containing the
|
||||
token and a `signed` object, both provided by the identity server.
|
||||
|
||||
If the invited homeserver is in the room the invite came from, it can
|
||||
auth the event and send it.
|
||||
|
||||
However, if the invited homeserver isn't in the room the invite came
|
||||
from, it will need to request the room's homeserver to auth the event.
|
||||
from, it will need to request the inviting homeserver to auth the event
|
||||
at the [`/exchange_third_party_invite`](#put_matrixfederationv1exchange_third_party_inviteroomid)
|
||||
endpoint.
|
||||
|
||||
{{% http-api spec="server-server" api="third_party_invite" %}}
|
||||
|
||||
|
|
@ -1045,11 +1048,10 @@ user's Matrix ID and the token delivered when the invite was stored,
|
|||
this verification will prove that the `m.room.member` invite event comes
|
||||
from the user owning the invited third-party identifier.
|
||||
|
||||
## Public Room Directory
|
||||
## Published Room Directory
|
||||
|
||||
To complement the [Client-Server
|
||||
API](/client-server-api)'s room directory,
|
||||
homeservers need a way to query the public rooms for another server.
|
||||
To complement the [room directory in the Client-Server API](/client-server-api#published-room-directory),
|
||||
homeservers need a way to query the published rooms of another server.
|
||||
This can be done by making a request to the `/publicRooms` endpoint for
|
||||
the server the room directory should be retrieved for.
|
||||
|
||||
|
|
@ -1337,7 +1339,7 @@ calculated as follows.
|
|||
The *content hash* of an event covers the complete event including the
|
||||
*unredacted* contents. It is calculated as follows.
|
||||
|
||||
First, any existing `unsigned`, `signature`, and `hashes` members are
|
||||
First, any existing `unsigned`, `signatures`, and `hashes` properties are
|
||||
removed. The resulting object is then encoded as [Canonical
|
||||
JSON](/appendices#canonical-json), and the JSON is hashed using
|
||||
SHA-256.
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ properties:
|
|||
type: string
|
||||
description: A unique, user-defined ID of the application service which will never change.
|
||||
url:
|
||||
type: string
|
||||
type: ["null", "string"]
|
||||
description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
|
||||
as_token:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -13,18 +13,21 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Application Service Room Directory API
|
||||
title: Matrix Client-Server Application Service Published Room Directory API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/directory/list/appservice/{networkId}/{roomId}":
|
||||
put:
|
||||
summary: Updates a room's visibility in the application service's room directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room on the application service's room
|
||||
summary: |-
|
||||
Updates a room's visibility in the application service's published room
|
||||
directory.
|
||||
description: |-
|
||||
Updates the visibility of a given room in the application service's
|
||||
published room directory.
|
||||
|
||||
This API is similar to the room directory visibility API used by clients
|
||||
to update the homeserver's more general room directory.
|
||||
This API is similar to the
|
||||
[visibility API](/client-server-api#put_matrixclientv3directorylistroomroomid)
|
||||
used by clients to update the homeserver's more general published room directory.
|
||||
|
||||
This API requires the use of an application service access token (`as_token`)
|
||||
instead of a typical client's access_token. This API cannot be invoked by
|
||||
|
|
|
|||
|
|
@ -87,12 +87,9 @@ paths:
|
|||
- public
|
||||
- private
|
||||
description: |-
|
||||
A `public` visibility indicates that the room will be shown
|
||||
in the published room list. A `private` visibility will hide
|
||||
the room from the published room list. Rooms default to
|
||||
`private` visibility if this key is not included. NB: This
|
||||
should not be confused with `join_rules` which also uses the
|
||||
word `public`.
|
||||
The room's visibility in the server's
|
||||
[published room directory](/client-server-api#published-room-directory).
|
||||
Defaults to `private`.
|
||||
room_alias_name:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
@ -109,15 +106,17 @@ paths:
|
|||
name:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.name` event will be sent
|
||||
into the room to indicate the name of the room. See Room
|
||||
Events for more information on `m.room.name`.
|
||||
If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
|
||||
will be sent into the room to indicate the name for the room.
|
||||
This overwrites any [`m.room.name`](/client-server-api/#mroomname)
|
||||
event in `initial_state`.
|
||||
topic:
|
||||
type: string
|
||||
description: |-
|
||||
If this is included, an `m.room.topic` event will be sent
|
||||
into the room to indicate the topic for the room. See Room
|
||||
Events for more information on `m.room.topic`.
|
||||
If this is included, an [`m.room.topic`](/client-server-api/#mroomtopic)
|
||||
event with a `text/plain` mimetype will be sent into the room
|
||||
to indicate the topic for the room. This overwrites any
|
||||
[`m.room.topic`](/client-server-api/#mroomtopic) event in `initial_state`.
|
||||
invite:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
title: "PublicRoomsChunk"
|
||||
title: "PublishedRoomsChunk"
|
||||
properties:
|
||||
canonical_alias:
|
||||
type: string
|
||||
|
|
@ -33,7 +33,9 @@ properties:
|
|||
example: "!abcdefg:example.org"
|
||||
topic:
|
||||
type: string
|
||||
description: The topic of the room, if any.
|
||||
description: |-
|
||||
The plain text topic of the room. Omitted if no `text/plain` mimetype
|
||||
exists in [`m.room.topic`](/client-server-api/#mroomtopic).
|
||||
example: "All things general"
|
||||
world_readable:
|
||||
type: boolean
|
||||
|
|
|
|||
|
|
@ -13,28 +13,15 @@
|
|||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
description: A list of the rooms on the server.
|
||||
description: A list of the published rooms on the server.
|
||||
required: ["chunk"]
|
||||
properties:
|
||||
chunk:
|
||||
type: array
|
||||
description: |-
|
||||
A paginated chunk of public rooms.
|
||||
A paginated chunk of published rooms.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: "public_rooms_chunk.yaml"
|
||||
- type: object
|
||||
title: PublicRoomsChunk
|
||||
properties:
|
||||
# Override description of join_rule
|
||||
join_rule:
|
||||
type: string
|
||||
description: |-
|
||||
The room's join rule. When not present, the room is assumed to
|
||||
be `public`. Note that rooms with `invite` join rules are not
|
||||
expected here, but rooms with `knock` rules are given their
|
||||
near-public nature.
|
||||
example: "public"
|
||||
$ref: "public_rooms_chunk.yaml"
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
@ -50,7 +37,7 @@ properties:
|
|||
total_room_count_estimate:
|
||||
type: integer
|
||||
description: |-
|
||||
An estimate on the total number of public rooms, if the
|
||||
An estimate on the total number of published rooms, if the
|
||||
server has an estimate.
|
||||
example: {
|
||||
"chunk": [
|
||||
|
|
|
|||
|
|
@ -13,14 +13,15 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Client-Server Room Directory API
|
||||
title: Matrix Client-Server Published Room Directory API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/directory/list/room/{roomId}":
|
||||
get:
|
||||
summary: Gets the visibility of a room in the directory
|
||||
description: Gets the visibility of a given room on the server's public room
|
||||
directory.
|
||||
description: |-
|
||||
Gets the visibility of a given room in the server's
|
||||
published room directory.
|
||||
operationId: getRoomVisibilityOnDirectory
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -32,7 +33,7 @@ paths:
|
|||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: The visibility of the room in the directory
|
||||
description: The visibility of the room in the directory.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -50,7 +51,7 @@ paths:
|
|||
"visibility": "public"
|
||||
}
|
||||
"404":
|
||||
description: The room is not known to the server
|
||||
description: The room is not known to the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -64,14 +65,13 @@ paths:
|
|||
tags:
|
||||
- Room discovery
|
||||
put:
|
||||
summary: Sets the visibility of a room in the room directory
|
||||
summary: Sets the visibility of a room in the directory
|
||||
description: |-
|
||||
Sets the visibility of a given room in the server's public room
|
||||
directory.
|
||||
Sets the visibility of a given room in the server's published room directory.
|
||||
|
||||
Servers may choose to implement additional access control checks
|
||||
here, for instance that room visibility can only be changed by
|
||||
the room creator or a server administrator.
|
||||
Servers MAY implement additional access control checks, for instance,
|
||||
to ensure that a room's visibility can only be changed by the room creator
|
||||
or a server administrator.
|
||||
operationId: setRoomVisibilityOnDirectory
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -97,11 +97,11 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
The new visibility setting for the room.
|
||||
Defaults to 'public'.
|
||||
Defaults to `public`.
|
||||
example: {
|
||||
"visibility": "public"
|
||||
}
|
||||
description: The new visibility for the room on the room directory.
|
||||
description: The new visibility for the room in the published room directory.
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
@ -114,7 +114,7 @@ paths:
|
|||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: The room is not known to the server
|
||||
description: The room is not known to the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -129,9 +129,9 @@ paths:
|
|||
- Room discovery
|
||||
/publicRooms:
|
||||
get:
|
||||
summary: Lists the public rooms on the server.
|
||||
summary: Lists a server's published room directory
|
||||
description: |-
|
||||
Lists the public rooms on the server.
|
||||
Lists a server's published room directory.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
|
@ -154,13 +154,13 @@ paths:
|
|||
- in: query
|
||||
name: server
|
||||
description: |-
|
||||
The server to fetch the public room lists from. Defaults to the
|
||||
local server. Case sensitive.
|
||||
The server to fetch the published room directory from. Defaults
|
||||
to the local server. Case sensitive.
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: A list of the rooms on the server.
|
||||
description: A list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -168,9 +168,9 @@ paths:
|
|||
tags:
|
||||
- Room discovery
|
||||
post:
|
||||
summary: Lists the public rooms on the server with optional filter.
|
||||
summary: Lists a server's published room directory with an optional filter
|
||||
description: |-
|
||||
Lists the public rooms on the server, with optional filter.
|
||||
Lists a server's published room directory with an optional filter.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
|
@ -182,8 +182,8 @@ paths:
|
|||
- in: query
|
||||
name: server
|
||||
description: |-
|
||||
The server to fetch the public room lists from. Defaults to the
|
||||
local server. Case sensitive.
|
||||
The server to fetch the published room directory from. Defaults
|
||||
to the local server. Case sensitive.
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
|
|
@ -253,7 +253,7 @@ paths:
|
|||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: A list of the rooms on the server.
|
||||
description: A filtered list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -45,7 +45,9 @@ paths:
|
|||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported.
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -88,12 +90,11 @@ paths:
|
|||
Reports an event as inappropriate to the server, which may then notify
|
||||
the appropriate people. The caller must be joined to the room to report
|
||||
it.
|
||||
|
||||
It might be possible for clients to deduce whether an event exists by
|
||||
timing the response, as only a report for an event that does exist
|
||||
will require the homeserver to check whether a user is joined to
|
||||
the room. To combat this, homeserver implementations should add
|
||||
a random delay when generating a response.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
event exists by timing the response. This is because only a report for an
|
||||
existing event will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportEvent
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -164,6 +165,88 @@ paths:
|
|||
}
|
||||
tags:
|
||||
- Reporting content
|
||||
"/users/{userId}/report":
|
||||
post:
|
||||
x-addedInMatrixVersion: "1.14"
|
||||
summary: Report a user as inappropriate.
|
||||
description: |-
|
||||
Reports a user as inappropriate to the server, which may then notify
|
||||
the appropriate people. How such information is delivered is left up to
|
||||
implementations. The caller is not required to be joined to any rooms
|
||||
that the reported user is joined to.
|
||||
|
||||
Clients may wish to [ignore](#ignoring-users) users after reporting them.
|
||||
|
||||
Clients could infer whether a reported user exists based on the 404 response.
|
||||
Homeservers that wish to conceal this information MAY return 200 responses
|
||||
regardless of the existence of the reported user.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
user exists by timing the response. This is because only a report for an
|
||||
existing user will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportUser
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user being reported.
|
||||
required: true
|
||||
example: "@someguy:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"reason": "this makes me sad"
|
||||
}
|
||||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
responses:
|
||||
"200":
|
||||
description: |
|
||||
The user has been reported successfully or the server chose
|
||||
to not disclose whether the users exists.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: |-
|
||||
The user was not found on the homeserver.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "The user was not found."
|
||||
}
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Reporting content
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -22,9 +22,12 @@ paths:
|
|||
description: |-
|
||||
Gets server admin contact and support page of the domain.
|
||||
|
||||
Like the [well-known discovery URI](/client-server-api/#well-known-uri),
|
||||
this should be accessed with the hostname of the homeserver by making a
|
||||
{{% boxes/note %}}
|
||||
Like the [well-known discovery URI](/client-server-api/#well-known-uris),
|
||||
this endpoint should be accessed with the hostname of the homeserver's
|
||||
[server name](/appendices/#server-name) by making a
|
||||
GET request to `https://hostname/.well-known/matrix/support`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that this endpoint is not necessarily handled by the homeserver.
|
||||
It may be served by another webserver, used for discovering support
|
||||
|
|
|
|||
|
|
@ -441,17 +441,57 @@ paths:
|
|||
"state": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
|
||||
"displayname": "Example user",
|
||||
"membership": "join"
|
||||
},
|
||||
"event_id": "$143273976499sgjks:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "@example:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 45603,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"timeline": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
|
||||
"displayname": "Alice Margatroid",
|
||||
"membership": "join",
|
||||
"reason": "Looking for support"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@alice:example.org",
|
||||
"state_key": "@alice:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
},
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
|
||||
"content": {
|
||||
"body": "This is an example text message",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<b>This is an example text message</b>",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
],
|
||||
"limited": true,
|
||||
|
|
|
|||
|
|
@ -57,9 +57,6 @@ paths:
|
|||
- A signature of the token, signed with the identity server's private key
|
||||
|
||||
- The matrix user ID who invited them to the room
|
||||
|
||||
If a token is requested from the identity server, the homeserver will
|
||||
append a `m.room.third_party_invite` event to the room.
|
||||
operationId: inviteBy3PID
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -72,6 +69,8 @@ paths:
|
|||
example: "!d41d8cd:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -90,7 +89,9 @@ paths:
|
|||
value: {}
|
||||
"403":
|
||||
description: |-
|
||||
You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
|
||||
You do not have permission to invite the user to the room. A
|
||||
meaningful `errcode` and description error text will be returned.
|
||||
Example reasons for rejections are:
|
||||
|
||||
- The invitee has been banned from the room.
|
||||
- The invitee is already a member of the room.
|
||||
|
|
|
|||
|
|
@ -20,10 +20,17 @@ paths:
|
|||
post:
|
||||
summary: Searches the user directory.
|
||||
description: |-
|
||||
Performs a search for users. The homeserver may
|
||||
determine which subset of users are searched, however the homeserver
|
||||
MUST at a minimum consider the users the requesting user shares a
|
||||
room with and those who reside in public rooms (known to the homeserver).
|
||||
Performs a search for users. The homeserver may determine which
|
||||
subset of users are searched. However, the homeserver MUST at a
|
||||
minimum consider users who are visible to the requester based
|
||||
on their membership in rooms known to the homeserver. This means:
|
||||
|
||||
- users that share a room with the requesting user
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`public` [join rule](#mroomjoin_rules)
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`world_readable` [history visibility](#room-history-visibility)
|
||||
|
||||
The search MUST consider local users to the homeserver, and SHOULD
|
||||
query remote users as part of the search.
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,12 @@ paths:
|
|||
suitably namespaced for each application and reduces the risk of
|
||||
clashes.
|
||||
|
||||
{{% boxes/note %}}
|
||||
This endpoint should be accessed with the hostname of the homeserver's
|
||||
[server name](/appendices/#server-name) by making a
|
||||
GET request to `https://hostname/.well-known/matrix/client`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that this endpoint is not necessarily handled by the homeserver,
|
||||
but by another webserver, to be used for discovering the homeserver URL.
|
||||
operationId: getWellknown
|
||||
|
|
|
|||
|
|
@ -43,7 +43,8 @@ paths:
|
|||
properties:
|
||||
public_key:
|
||||
type: string
|
||||
description: Unpadded Base64 encoded public key.
|
||||
description: |-
|
||||
[Unpadded Base64](/appendices/#unpadded-base64)-encoded public key.
|
||||
required:
|
||||
- public_key
|
||||
examples:
|
||||
|
|
@ -74,7 +75,8 @@ paths:
|
|||
- in: query
|
||||
name: public_key
|
||||
required: true
|
||||
description: The unpadded base64-encoded public key to check.
|
||||
description: |-
|
||||
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public key to check.
|
||||
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -105,7 +107,14 @@ paths:
|
|||
- in: query
|
||||
name: public_key
|
||||
required: true
|
||||
description: The unpadded base64-encoded public key to check.
|
||||
description: |-
|
||||
The [unpadded Base64](/appendices/#unpadded-base64)-encoded public
|
||||
key to check.
|
||||
|
||||
This MUST be the exact same encoded string returned in the response
|
||||
of the [`/store-invite`](/identity-service-api/#post_matrixidentityv2store-invite)
|
||||
endpoint, or found in the corresponding [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
|
||||
event, so it may use the standard or URL-safe alphabets.
|
||||
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
|
||||
schema:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
(if present) from the request here.
|
||||
|
||||
Also, the generated ephemeral public key will be listed as valid on
|
||||
requests to `/_matrix/identity/v2/pubkey/ephemeral/isvalid`.
|
||||
requests to [`/_matrix/identity/v2/pubkey/ephemeral/isvalid`](/identity-service-api/#get_matrixidentityv2pubkeyephemeralisvalid).
|
||||
|
||||
Currently, invites may only be issued for 3pids of the `email` medium.
|
||||
|
||||
|
|
@ -70,10 +70,14 @@ paths:
|
|||
room_id:
|
||||
type: string
|
||||
description: The Matrix room ID to which the user is invited
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: "!something:example.org"
|
||||
sender:
|
||||
type: string
|
||||
description: The Matrix user ID of the inviting user
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@bob:example.com"
|
||||
room_alias:
|
||||
type: string
|
||||
|
|
@ -81,12 +85,16 @@ paths:
|
|||
The Matrix room alias for the room to which the user is
|
||||
invited. This should be retrieved from the `m.room.canonical_alias`
|
||||
state event.
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
example: "#somewhere:example.org"
|
||||
room_avatar_url:
|
||||
type: string
|
||||
description: |-
|
||||
The Content URI for the room to which the user is invited. This should
|
||||
be retrieved from the `m.room.avatar` state event.
|
||||
format: mx-mxc-uri
|
||||
pattern: "^mxc:\\/\\/"
|
||||
example: mxc://example.org/s0meM3dia
|
||||
room_join_rules:
|
||||
type: string
|
||||
|
|
@ -108,6 +116,8 @@ paths:
|
|||
type: string
|
||||
description: The Content URI for the avatar of the user ID initiating the
|
||||
invite.
|
||||
format: mx-mxc-uri
|
||||
pattern: "^mxc:\\/\\/"
|
||||
example: mxc://example.org/an0th3rM3dia
|
||||
room_type:
|
||||
type: string
|
||||
|
|
@ -146,7 +156,7 @@ paths:
|
|||
public_key:
|
||||
type: string
|
||||
description: |
|
||||
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
|
||||
The public key, encoded using standard or URL-safe [unpadded Base64](/appendices/#unpadded-base64).
|
||||
key_validity_url:
|
||||
type: string
|
||||
description: |
|
||||
|
|
|
|||
|
|
@ -41,13 +41,6 @@ properties:
|
|||
type: object
|
||||
description: The content of the event.
|
||||
example: {"key": "value"}
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
|
|
|
|||
|
|
@ -28,6 +28,13 @@ allOf:
|
|||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -17,6 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
|
|||
example:
|
||||
$ref: "../examples/pdu_v11.json"
|
||||
allOf:
|
||||
# v11 is the v4 event, but without redacts.
|
||||
# v11 is the v6 event, but without redacts.
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -24,6 +24,13 @@ allOf:
|
|||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def/456+oldevent"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
|
|
|
|||
|
|
@ -26,3 +26,10 @@ allOf:
|
|||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def_456-oldevent"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
|
|||
36
data/api/server-server/definitions/pdu_v6.yaml
Normal file
36
data/api/server-server/definitions/pdu_v6.yaml
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Copyright 2025 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: |-
|
||||
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
|
||||
example:
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def_456-oldevent"
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -20,7 +20,7 @@ paths:
|
|||
put:
|
||||
summary: Invites a remote user to a room
|
||||
description: |-
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
homeserver and the invited homeserver, it can be sent to all of the servers in the
|
||||
room by the inviting homeserver.
|
||||
|
||||
|
|
@ -32,6 +32,10 @@ paths:
|
|||
[room version specification](/rooms) for precise event formats. **The request and response
|
||||
bodies here describe the common event fields in more detail and may be missing other
|
||||
required fields for a PDU.**
|
||||
|
||||
Also note that if the remote homeserver is already in the room, it will receive the
|
||||
invite event twice; once through this endpoint, and again through a [federation
|
||||
transaction](/server-server-api/#transactions).
|
||||
operationId: sendInviteV1
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ paths:
|
|||
This API is nearly identical to the v1 API with the exception of the request
|
||||
body being different, and the response format fixed.
|
||||
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
Invites a remote user to a room. Once the event has been signed by both the inviting
|
||||
homeserver and the invited homeserver, it can be sent to all of the servers in the
|
||||
room by the inviting homeserver.
|
||||
|
||||
|
|
@ -36,6 +36,10 @@ paths:
|
|||
[room version specification](/rooms) for precise event formats. **The request and response
|
||||
bodies here describe the common event fields in more detail and may be missing other
|
||||
required fields for a PDU.**
|
||||
|
||||
Also note that if the remote homeserver is already in the room, it will receive the
|
||||
invite event twice; once through this endpoint, and again through a [federation
|
||||
transaction](/server-server-api/#transactions).
|
||||
operationId: sendInviteV2
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
|
|||
|
|
@ -13,16 +13,20 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Federation Public Rooms API
|
||||
title: Matrix Federation Published Room Directory API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/publicRooms:
|
||||
get:
|
||||
summary: Get all the public rooms for a homeserver
|
||||
summary: Lists the server's published room directory
|
||||
description: |-
|
||||
Gets all the public rooms for the homeserver. This should not return
|
||||
rooms that are listed on another homeserver's directory, just those
|
||||
listed on the receiving homeserver's directory.
|
||||
Lists the server's published room directory.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
||||
This SHOULD not return rooms that are listed on another homeserver's directory,
|
||||
just those listed on the receiving homeserver's directory.
|
||||
operationId: getPublicRooms
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
@ -62,21 +66,18 @@ paths:
|
|||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: The public room list for the homeserver.
|
||||
description: A list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/public_rooms_response.yaml
|
||||
post:
|
||||
summary: Gets the public rooms on the server with optional filter.
|
||||
summary: Lists the server's published room directory with an optional filter
|
||||
description: |-
|
||||
Lists the public rooms on the server, with optional filter.
|
||||
Lists the server's published room directory with an optional filter.
|
||||
|
||||
This API returns paginated responses. The rooms are ordered by the number
|
||||
of joined members, with the largest rooms first.
|
||||
|
||||
Note that this endpoint receives and returns the same format that is seen
|
||||
in the Client-Server API's `POST /publicRooms` endpoint.
|
||||
operationId: queryPublicRooms
|
||||
security:
|
||||
- signedRequest: []
|
||||
|
|
@ -147,69 +148,11 @@ paths:
|
|||
required: true
|
||||
responses:
|
||||
"200":
|
||||
description: A list of the rooms on the server.
|
||||
description: A filtered list of the published rooms on the server.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
description: A list of the rooms on the server.
|
||||
required:
|
||||
- chunk
|
||||
properties:
|
||||
chunk:
|
||||
title: PublicRoomsChunks
|
||||
type: array
|
||||
description: A paginated chunk of public rooms.
|
||||
items:
|
||||
allOf:
|
||||
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
|
||||
- type: object
|
||||
properties:
|
||||
# Override description of join_rule
|
||||
join_rule:
|
||||
type: string
|
||||
description: |-
|
||||
The room's join rule. When not present, the room is assumed to
|
||||
be `public`. Note that rooms with `invite` join rules are not
|
||||
expected here, but rooms with `knock` rules are given their
|
||||
near-public nature.
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
A pagination token for the response. The absence of this token
|
||||
means there are no more results to fetch and the client should
|
||||
stop paginating.
|
||||
prev_batch:
|
||||
type: string
|
||||
description: |-
|
||||
A pagination token that allows fetching previous results. The
|
||||
absence of this token means there are no results before this
|
||||
batch, i.e. this is the first batch.
|
||||
total_room_count_estimate:
|
||||
type: integer
|
||||
description: |-
|
||||
An estimate on the total number of public rooms, if the
|
||||
server has an estimate.
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"chunk": [
|
||||
{
|
||||
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
|
||||
"guest_can_join": false,
|
||||
"name": "CHEESE",
|
||||
"num_joined_members": 37,
|
||||
"room_id": "!ol19s:bleecker.street",
|
||||
"topic": "Tasty tasty cheese",
|
||||
"world_readable": true,
|
||||
"join_rule": "public",
|
||||
"room_type": "m.space"
|
||||
}
|
||||
],
|
||||
"next_batch": "p190q",
|
||||
"prev_batch": "p1902",
|
||||
"total_room_count_estimate": 115
|
||||
}
|
||||
$ref: ../client-server/definitions/public_rooms_response.yaml
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue