Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-14 07:24:11 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' into clarify-identifier-localparts

Browse source
This commit is contained in:
Travis Ralston 2023-08-09 12:04:00 -06:00
parent 6215072fd3 f5035b8e02
commit ec55c38339
243 changed files with 16647 additions and 13045 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
.github/ISSUE_TEMPLATE/release.md vendored Normal file
View file

@ -0,0 +1,34 @@
---
name: [SCT] Release checklist
about: Used by the Spec Core Team to create a new release.
title: 'Matrix 1.X'
labels: 'release-blocker'
assignees: ''
---
<!-- ------------------------------------------------------------------------ -->
<!-- Please asssign the release coordinator (probably yourself) to this issue -->
<!-- ------------------------------------------------------------------------ -->
Date: **Thursday, May 25, 2023** <!-- CHANGE ME -->
Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
* [ ] Blog post written
* [ ] Check for release blockers that may have been missed
* [ ] Review/fix the changelog
Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
* [ ] Branch stuffs
* [ ] Github release artifact
* [ ] Published to spec.matrix.org
* [ ] All links work
* [ ] Publish blog post
* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted
* [ ] Post to Twitter/Mastodon
* [ ] Close this issue
Known release blockers:
* [ ] <!-- Issue/PR link -->

19
.github/workflows/main.yml vendored
View file

@ -23,16 +23,9 @@ jobs:
uses: actions/setup-node@v2
with:
node-version: '14'
- name: "⚙️ npm"
working-directory: "./scripts"
run: |
npm install
- name: "🔎 Run validator"
working-directory: "./scripts"
run: |
node validator.js -s "../data/api/application-service"
node validator.js -s "../data/api/client-server"
node validator.js -s "../data/api/push-gateway"
npx @redocly/cli@latest lint data/api/*/*.yaml
check-examples:
name: "🔎 Check Event schema examples"
@ -93,18 +86,26 @@ jobs:
pip install -r scripts/requirements.txt
- name: "📦 Asset creation"
run: |
if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
export RELEASE="${GITHUB_REF/refs\/tags\//}"
else
export RELEASE="unstable"
fi
# The output path matches the final deployment path at spec.matrix.org
scripts/dump-swagger.py \
--base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
--api application-service \
-r "$RELEASE" \
-o spec/application-service-api/api.json
scripts/dump-swagger.py \
--base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
--api client-server \
-r "$RELEASE" \
-o spec/client-server-api/api.json
scripts/dump-swagger.py \
--base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
--api push-gateway \
-r "$RELEASE" \
-o spec/push-gateway-api/api.json
tar -czf openapi.tar.gz spec
- name: "📤 Artifact upload"
@ -147,7 +148,7 @@ jobs:
- name: "➕ Setup Hugo"
uses: peaceiris/actions-hugo@c03b5dbed22245418539b65eb9a3b1d5fdd9a0a6
with:
hugo-version: '0.93.3'
hugo-version: '0.113.0'
extended: true
- name: "📥 Source checkout"
uses: actions/checkout@v2

3
.gitmodules vendored
View file

@ -1,4 +1,7 @@
[submodule "themes/docsy"]
path = themes/docsy
# We use our own forked version of the Docsy theme,
# to avoid loading fonts from CDNs, which Docsy currently
# doesn't support (see https://github.com/google/docsy/issues/605).
url = https://github.com/matrix-org/docsy.git
branch = master

79
assets/scss/custom.scss
View file

@ -68,9 +68,8 @@ Custom SCSS for the Matrix spec
margin-top: 1rem;
}
&>.td-sidebar-nav__section > li > a.td-sidebar-link {
font-weight: $font-weight-bold;
font-size: 1.3rem;
.td-sidebar-nav__section .ul-1 ul {
padding-left: 0;
}
/* This is to make the width of the items that have sub-items (like room versions)
@ -79,12 +78,20 @@ Custom SCSS for the Matrix spec
padding-right: 0 !important;
}
a.indent-1 {
.ul-1 > li > a {
padding-left: 1rem !important;
}
a.indent-2 {
padding-left: 2rem;
.ul-2 > li > a {
padding-left: 2rem !important;
}
a.td-sidebar-link.tree-root {
color: $gray-800;
font-weight: $font-weight-bold;
font-size: 1.3rem;
margin-bottom: 0;
border-bottom: none;
}
a, a.td-sidebar-link {
@ -103,7 +110,6 @@ Custom SCSS for the Matrix spec
&.active, &active:hover {
background-color: $secondary-background;
font-weight: $font-weight-normal;
}
}
}
@ -344,19 +350,37 @@ footer {
}
table {
/* Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
* tables with a "display" property of "block".
*
* However, for "table-layout: fixed" to be effective, an element must have a
* "display" property of "table".
*
* Thus, we override the "display" property here. This may no longer be necessary once
* Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
* For more details, see
* https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
display: table;
table-layout: fixed;
width: 100%;
@media (max-width: 800px) {
/* Docsy by default applies `overflow-x: auto;` to tables, which
* results in annoying horizontal scrolling on mobile, so we instead
* switch to a fixed table layout on a narrow browser width.
* (On a wider width the default auto table-layout provides better readability.)
*
* Docsy makes all tables "responsive tables", which causes Bootstrap 4 to create
* tables with a "display" property of "block".
* However, for "table-layout: fixed" to be effective, an element must have a
* "display" property of "table".
*
* Thus, we override the "display" property here. This may no longer be necessary once
* Docsy updates to Bootstrap v5+: https://github.com/google/docsy/issues/470.
* For more details, see
* https://github.com/matrix-org/matrix-spec/pull/1295/files#r1010759688 */
display: table;
table-layout: fixed;
width: 100%;
.col-name, .col-type, .col-status {
width: 25%;
}
.col-description {
width: 50%;
}
.col-status-description {
width: 75%;
}
}
// add some space between two tables when they are right next to each other
& + table {
@ -374,7 +398,7 @@ footer {
padding: 1rem;
}
&.object-table, &.response-table {
&.object-table, &.response-table, &.content-type-table {
border: 1px $table-border-color solid;
caption {
@ -403,19 +427,6 @@ footer {
&.basic-info th {
width: 15rem;
}
.col-name, .col-type, .col-status {
width: 25%;
}
.col-description {
width: 50%;
}
.col-status-description {
width: 75%;
}
}
pre {

1
changelogs/appendices/newsfragments/1468.clarification
View file

@ -1 +0,0 @@
Clarify that the term "Canonical JSON" is a specific thing within the matrix specification.

1
changelogs/appendices/newsfragments/1483.clarification
View file

@ -1 +0,0 @@
Remove references to groups

1
changelogs/appendices/newsfragments/1484.clarification
View file

@ -1 +0,0 @@
Clarifications of event ID formats in early room versions

1
changelogs/appendices/newsfragments/1573.clarification Normal file
View file

@ -0,0 +1 @@
Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten

1
changelogs/appendices/newsfragments/1583.feature Normal file
View file

@ -0,0 +1 @@
Allow `+` in Matrix IDs, per [MSC4009](https://github.com/matrix-org/matrix-spec-proposals/pull/4009).

1
changelogs/application_service/newsfragments/1447.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/application_service/newsfragments/1584.clarification Normal file
View file

@ -0,0 +1 @@
Fix JSON schema of custom fields in query.

1
changelogs/client_server/newsfragments/1424.clarification
View file

@ -1 +0,0 @@
Clarify the sections of the specification concerning aggregation of child events.

1
changelogs/client_server/newsfragments/1432.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1439.clarification
View file

@ -1 +0,0 @@
Clarify that reply chain fallback for threads may not be present.

1
changelogs/client_server/newsfragments/1440.feature
View file

@ -1 +0,0 @@
Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925).

1
changelogs/client_server/newsfragments/1441.clarification
View file

@ -1 +0,0 @@
Clarify what event property the content-specific push rules match against.

1
changelogs/client_server/newsfragments/1447.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1449.clarification
View file

@ -1 +0,0 @@
Clarify the semantics that make requests idempotent.

1
changelogs/client_server/newsfragments/1455.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1457.clarification
View file

@ -1 +0,0 @@
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

1
changelogs/client_server/newsfragments/1461.clarification
View file

@ -1 +0,0 @@
Improve documentation of how clients use push rules.

1
changelogs/client_server/newsfragments/1463.clarification
View file

@ -1 +0,0 @@
Clarify that servers should enforce a default `limit` on a filter if one is not specified.

1
changelogs/client_server/newsfragments/1464.clarification
View file

@ -1 +0,0 @@
Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980).

1
changelogs/client_server/newsfragments/1464.feature
View file

@ -1 +0,0 @@
Add new push rule conditions: `event_property_is` and `event_property_contains` from [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966).

1
changelogs/client_server/newsfragments/1465.clarifications
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1474.clarification
View file

@ -1 +0,0 @@
Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks.

1
changelogs/client_server/newsfragments/1475.feature
View file

@ -1 +0,0 @@
Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677).

1
changelogs/client_server/newsfragments/1479.clarification
View file

@ -1 +0,0 @@
Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room.

1
changelogs/client_server/newsfragments/1485.clarification
View file

@ -1 +0,0 @@
Remove fictitious `token` parameter on `/keys/query` endpoint

1
changelogs/client_server/newsfragments/1487.clarification
View file

@ -1 +0,0 @@
Fix rendering of properties with a list of types

1
changelogs/client_server/newsfragments/1500.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/1552.clarification Normal file
View file

@ -0,0 +1 @@
Fix missing `type` property in the JSON schema definition of the `m.reaction` event. Contributed by @chebureki.

1
changelogs/client_server/newsfragments/1563.clarification Normal file
View file

@ -0,0 +1 @@
Make sure examples types match schema in definitions.

1
changelogs/client_server/newsfragments/1564.clarification Normal file
View file

@ -0,0 +1 @@
Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas.

1
changelogs/client_server/newsfragments/1578.clarification Normal file
View file

@ -0,0 +1 @@
Fix broken header formatting. Contributed by @midnightveil.

1
changelogs/client_server/newsfragments/1579.clarification Normal file
View file

@ -0,0 +1 @@
Render binary request and response bodies.

1
changelogs/client_server/newsfragments/1585.clarification Normal file
View file

@ -0,0 +1 @@
Remove unnecessary `oneOf`s in JSON schemas.

1
changelogs/client_server/newsfragments/1590.clarification Normal file
View file

@ -0,0 +1 @@
Fix description of MAC calculation in SAS verification.

1
changelogs/client_server/newsfragments/1593.clarification Normal file
View file

@ -0,0 +1 @@
Update link to SAS emoji definition data.

0
changelogs/client_server/newsfragments/1442.clarification → changelogs/client_server/newsfragments/1597.clarification
View file

1
changelogs/identity_service/newsfragments/1457.clarification
View file

@ -1 +0,0 @@
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

1
changelogs/identity_service/newsfragments/1563.clarification Normal file
View file

@ -0,0 +1 @@
Make sure examples types match schema in definitions.

1
changelogs/internal/newsfragments/1310.feature Normal file
View file

@ -0,0 +1 @@
Upgrade Swagger data to OpenAPI 3.1.

1
changelogs/internal/newsfragments/1444.clarification
View file

@ -1 +0,0 @@
Update references to Inter font.

1
changelogs/internal/newsfragments/1446.clarification
View file

@ -1 +0,0 @@
Endpoint disclosures now hide everything but the URL.

1
changelogs/internal/newsfragments/1476.clarification
View file

@ -1 +0,0 @@
Minor cleanups to the GitHub Actions workflows

1
changelogs/internal/newsfragments/1542.clarification Normal file
View file

@ -0,0 +1 @@
Update the CI to validate the file extension of changelog entries.

1
changelogs/internal/newsfragments/1549.clarification Normal file
View file

@ -0,0 +1 @@
Disclosure sections now only display their title when collapsed.

1
changelogs/internal/newsfragments/1551.clarification Normal file
View file

@ -0,0 +1 @@
Fix the sidebar in recent versions of Hugo

1
changelogs/internal/newsfragments/1556.clarification Normal file
View file

@ -0,0 +1 @@
Bump jsonschema to validate JSON Schemas against Draft 2020-12.

1
changelogs/internal/newsfragments/1558.clarification Normal file
View file

@ -0,0 +1 @@
Use Redocly CLI to validate OpenAPI definitions.

1
changelogs/internal/newsfragments/1561.clarification Normal file
View file

@ -0,0 +1 @@
Use tag name as the OpenAPI definition version.

1
changelogs/internal/newsfragments/1562.clarification Normal file
View file

@ -0,0 +1 @@
Make sure version in x-changedInMatrixVersion is a string.

1
changelogs/internal/newsfragments/1582.clarification Normal file
View file

@ -0,0 +1 @@
Clarify usage of ABNF for grammar in the documentation style guide.

1
changelogs/internal/newsfragments/1591.clarification Normal file
View file

@ -0,0 +1 @@
Update the version of Hugo used to render the spec to v0.113.0.

1
changelogs/internal/newsfragments/1598.clarification Normal file
View file

@ -0,0 +1 @@
Fix rendered changelog with new version of towncrier.

1
changelogs/internal/newsfragments/1601.clarification Normal file
View file

@ -0,0 +1 @@
Improve the layout of tables on desktop displays. Contributed by Martin Fischer.

53
changelogs/pyproject.toml
View file

@ -1,39 +1,66 @@
[tool.towncrier]
version = "unused"
filename = "../rendered.md"
issue_format = "[#{issue}](https://github.com/matrix-org/matrix-spec/issues/{issue})"
title_format = "### {name}" # Matches rendered spec, even if awkward
underlines = " " # 3 spaces intentionally to hide RST headings
# Note: The names below have the <strong> tag built-in so the rendered spec *and* the generated
# changelog can benefit from sane headings.
filename = "rendered.md"
template = "template.md.jinja"
[[tool.towncrier.type]]
directory = "breaking"
name = "<strong>Breaking Changes</strong>"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "<strong>Deprecations</strong>"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "<strong>New Endpoints</strong>"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "removal"
name = "<strong>Removed Endpoints</strong>"
name = "Removed Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "<strong>Backwards Compatible Changes</strong>"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "<strong>Spec Clarifications</strong>"
name = "Spec Clarifications"
showcontent = true
[[tool.towncrier.section]]
name = "Client-Server API"
path = "client_server"
[[tool.towncrier.section]]
name = "Server-Server API"
path = "server_server"
[[tool.towncrier.section]]
name = "Application Service API"
path = "application_service"
[[tool.towncrier.section]]
name = "Identity Service API"
path = "identity_service"
[[tool.towncrier.section]]
name = "Push Gateway API"
path = "push_gateway"
[[tool.towncrier.section]]
name = "Room Versions"
path = "room_versions"
[[tool.towncrier.section]]
name = "Appendices"
path = "appendices"
[[tool.towncrier.section]]
name = "Internal Changes/Tooling"
path = "internal"

1
changelogs/room_versions/newsfragments/1484.clarification
View file

@ -1 +0,0 @@
Clarifications of event ID formats in early room versions

1
changelogs/server_server/newsfragments/1431.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/server_server/newsfragments/1447.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/server_server/newsfragments/1454.clarification
View file

@ -1 +0,0 @@
Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`.

1
changelogs/server_server/newsfragments/1457.clarification
View file

@ -1 +0,0 @@
Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance.

1
changelogs/server_server/newsfragments/1466.clarification
View file

@ -1 +0,0 @@
Fix various typos throughout the specification.

1
changelogs/server_server/newsfragments/1473.clarification
View file

@ -1 +0,0 @@
* Remove leftover `{key_id}` from `/_matrix/key/v2/server/`

1
changelogs/server_server/newsfragments/1521.clarification Normal file
View file

@ -0,0 +1 @@
Document why `/state_ids` can respond with a 404.

1
changelogs/server_server/newsfragments/1559.clarification Normal file
View file

@ -0,0 +1 @@
Fix definition of response of `POST /_matrix/federation/v1/user/keys/claim`.

1
changelogs/server_server/newsfragments/1560.clarification Normal file
View file

@ -0,0 +1 @@
Fix level of examples in server keys definition.

1
changelogs/server_server/newsfragments/1563.clarification Normal file
View file

@ -0,0 +1 @@
Make sure examples types match schema in definitions.

1
changelogs/server_server/newsfragments/1564.clarification Normal file
View file

@ -0,0 +1 @@
Allow `null` in `room_types` in `POST /publicRooms` endpoints schemas.

1
changelogs/server_server/newsfragments/1578.clarification Normal file
View file

@ -0,0 +1 @@
Fix broken header formatting. Contributed by @midnightveil.

24
changelogs/template.md.jinja Normal file
View file

@ -0,0 +1,24 @@
{% for section_name, section in sections.items() %}
{% if section_name %}
### {{section_name}}
{% endif %}
{% if section %}
{% for category, val in definitions.items() if category in section %}
**{{ definitions[category]['name'] }}**
{% for content, issues in section[category].items() %}
- {{ content }} (
{%- for issue in issues %}
[{{issue}}](https://github.com/matrix-org/matrix-spec/issues/{{issue|trim('#')}}){% if not loop.last %}, {% endif %}
{%- endfor %}
)
{% endfor %}
{% endfor %}
{% else %}
No significant changes.
{% endif %}
{% endfor %}

8
config.toml
View file

@ -53,8 +53,8 @@ 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. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created.
# major = "1"
# minor = "6"
# release_date = "February 14, 2023"
# minor = "7"
# release_date = "May 25, 2023"
# User interface configuration
[params.ui]
@ -62,6 +62,10 @@ current_version_url = "https://spec.matrix.org/latest"
footer_about_disable = false
# Collapse HTTP API and event <details> elements
rendered_data_collapsed = false
# Hide the search entry in the sidebar
sidebar_search_disable = true
# Only show the current page's ancestors, siblings and direct descendants in the sidebar menu
sidebar_menu_compact = true
[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.

4
content/_index.md
View file

@ -357,8 +357,8 @@ servers that are in the room that can be used to join via.
HTTP GET
#matrix:example.org !aaabaa:matrix.org
| ^
| |
| ^
| |
_______V____________________|____
| example.org |
| Mappings: |

24
content/appendices.md
View file

@ -90,7 +90,8 @@ To ensure that all implementations use the same JSON encoding we define
We define this encoding for a value to be the shortest
UTF-8 JSON encoding with dictionary keys lexicographically sorted by
Unicode codepoint. Numbers in the JSON must be integers in the range
`[-(2**53)+1, (2**53)-1]`.
`[-(2**53)+1, (2**53)-1]`, represented without exponents or decimal
places, and negative zero `-0` MUST NOT appear.
We pick UTF-8 as the encoding as it should be available to all platforms
and JSON received from the network is likely to be already encoded using
@ -304,6 +305,21 @@ The following canonical JSON should be produced:
{"a":null}
```
Given the following JSON object:
```json
{
"a": -0,
"b": 1e10
}
```
The following canonical JSON should be produced:
```json
{"a":0,"b":10000000000}
```
### Signing Details
JSON is signed by encoding the JSON object without `signatures` or keys
@ -524,6 +540,8 @@ be represented with a `domain` component under some conditions - see the
#### User Identifiers
{{% changed-in v="1.8" %}}
Users within Matrix are uniquely identified by their Matrix user ID. The
user ID is namespaced to the homeserver which allocated the account and
has the form:
@ -532,7 +550,7 @@ has the form:
The `localpart` of a user ID is an opaque identifier for that user. It
MUST NOT be empty, and MUST contain only the characters `a-z`, `0-9`,
`.`, `_`, `=`, `-`, and `/`.
`.`, `_`, `=`, `-`, `/`, and `+`.
The `domain` of a user ID is the [server name](#server-name) of the
homeserver which allocated the account.
@ -546,7 +564,7 @@ The complete grammar for a legal user ID is:
user_id_localpart = 1*user_id_char
user_id_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "." / "=" / "_" / "/"
/ "-" / "." / "=" / "_" / "/" / "+"
{{% boxes/rationale %}}
A number of factors were considered when defining the allowable

57
content/application-service-api.md
View file

@ -207,6 +207,54 @@ processed the events.
{{% http-api spec="application-service" api="transactions" %}}
#### Pinging
{{% added-in v="1.7" %}}
The application service API includes a ping mechanism to allow
appservices to ensure that the homeserver can reach the appservice.
Appservices may use this mechanism to detect misconfigurations and
report them appropriately.
Implementations using this mechanism should take care to not fail
entirely in the event of temporary issues, e.g. gracefully handling
cases where the appservice is started before the homeserver.
The mechanism works as follows (note: the human-readable `error` fields
have been omitted for brevity):
**Typical**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
HS <--- AS : 200 OK {}
AS <--- HS : 200 OK {"duration_ms": 123}
```
**Incorrect `hs_token`**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body": "{\"errcode\": \"M_FORBIDDEN\"}"}
```
**Can't connect to appservice**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
```
The `/_matrix/app/v1/ping` endpoint is described here. The
[`/_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping)
endpoint is under the Client-Server API extensions section below.
{{% http-api spec="application-service" api="ping" %}}
#### Querying
The application service API includes two querying APIs: for room aliases
@ -388,6 +436,15 @@ an application service-defined namespace will receive the same
`M_EXCLUSIVE` error code, but only if the application service has
defined the namespace as `exclusive`.
#### Pinging
{{% added-in v="1.7" %}}
This is the client-server API companion endpoint for the
[pinging](#pinging) mechanism described above.
{{% http-api spec="client-server" api="appservice_ping" %}}
#### Using `/sync` and `/events`
Application services wishing to use `/sync` or `/events` from the

147
content/changelog/v1.7.md Normal file
View file

@ -0,0 +1,147 @@
---
date: 2023-05-25T09:47:21-06:00
---
<!--
This is a header file for the generated changelog.
Variables:
v1.7 = Replaced by the version number (eg: v1.2)
May 25, 2023 = Replaced by the date (eg: April 01, 2021)
-->
## v1.7
<table class="release-info">
<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.7">https://github.com/matrix-org/matrix-spec/tree/v1.7</a></td>
<tr><th>Release date</th><td>May 25, 2023</td>
</table>
<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
### Client-Server API
<strong>New Endpoints</strong>
- [`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499))
- [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499))
- [`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530))
<strong>Backwards Compatible Changes</strong>
- Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). ([#1440](https://github.com/matrix-org/matrix-spec/issues/1440), [#1525](https://github.com/matrix-org/matrix-spec/issues/1525))
- Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464))
- Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). ([#1475](https://github.com/matrix-org/matrix-spec/issues/1475), [#1531](https://github.com/matrix-org/matrix-spec/issues/1531))
- Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499), [#1510](https://github.com/matrix-org/matrix-spec/issues/1510))
- Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). ([#1508](https://github.com/matrix-org/matrix-spec/issues/1508))
- Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). ([#1511](https://github.com/matrix-org/matrix-spec/issues/1511), [#1540](https://github.com/matrix-org/matrix-spec/issues/1540))
- Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). ([#1526](https://github.com/matrix-org/matrix-spec/issues/1526))
- Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). ([#1529](https://github.com/matrix-org/matrix-spec/issues/1529))
- Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530))
<strong>Spec Clarifications</strong>
- Clarify the sections of the specification concerning aggregation of child events. ([#1424](https://github.com/matrix-org/matrix-spec/issues/1424))
- Fix various typos throughout the specification. ([#1432](https://github.com/matrix-org/matrix-spec/issues/1432), [#1442](https://github.com/matrix-org/matrix-spec/issues/1442), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1455](https://github.com/matrix-org/matrix-spec/issues/1455), [#1465](https://github.com/matrix-org/matrix-spec/issues/1465), [#1500](https://github.com/matrix-org/matrix-spec/issues/1500), [#1509](https://github.com/matrix-org/matrix-spec/issues/1509))
- Clarify that reply chain fallback for threads might not be present. ([#1439](https://github.com/matrix-org/matrix-spec/issues/1439))
- Clarify what event property the content-specific push rules match against. ([#1441](https://github.com/matrix-org/matrix-spec/issues/1441))
- Clarify the semantics that make requests idempotent. ([#1449](https://github.com/matrix-org/matrix-spec/issues/1449))
- Improve documentation of how clients use push rules. ([#1461](https://github.com/matrix-org/matrix-spec/issues/1461))
- Clarify that servers should enforce a default `limit` on a filter if one is not specified. ([#1463](https://github.com/matrix-org/matrix-spec/issues/1463))
- Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464))
- Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. ([#1474](https://github.com/matrix-org/matrix-spec/issues/1474))
- Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. ([#1479](https://github.com/matrix-org/matrix-spec/issues/1479))
- Remove fictitious `token` parameter on `/keys/query` endpoint. ([#1485](https://github.com/matrix-org/matrix-spec/issues/1485))
- Fix rendering of properties with a list of types. ([#1487](https://github.com/matrix-org/matrix-spec/issues/1487))
- Clarify parts of the cross-signing signature upload request. ([#1495](https://github.com/matrix-org/matrix-spec/issues/1495))
- Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). ([#1501](https://github.com/matrix-org/matrix-spec/issues/1501))
- Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. ([#1507](https://github.com/matrix-org/matrix-spec/issues/1507))
- Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535))
### Server-Server API
<strong>Spec Clarifications</strong>
- Fix various typos throughout the specification. ([#1431](https://github.com/matrix-org/matrix-spec/issues/1431), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1466](https://github.com/matrix-org/matrix-spec/issues/1466), [#1518](https://github.com/matrix-org/matrix-spec/issues/1518))
- Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. ([#1454](https://github.com/matrix-org/matrix-spec/issues/1454))
- Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. ([#1473](https://github.com/matrix-org/matrix-spec/issues/1473))
- Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536))
### Application Service API
<strong>New Endpoints</strong>
- [`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516))
- [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516))
<strong>Backwards Compatible Changes</strong>
- Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516), [#1541](https://github.com/matrix-org/matrix-spec/issues/1541))
<strong>Spec Clarifications</strong>
- Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447))
### Identity Service API
<strong>Spec Clarifications</strong>
- Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486))
### Push Gateway API
No significant changes.
### Room Versions
<strong>Spec Clarifications</strong>
- Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
### Appendices
<strong>Spec Clarifications</strong>
- Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. ([#1468](https://github.com/matrix-org/matrix-spec/issues/1468))
- Remove references to groups. ([#1483](https://github.com/matrix-org/matrix-spec/issues/1483))
- Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484))
### Internal Changes/Tooling
<strong>Spec Clarifications</strong>
- Update references to Inter font. ([#1444](https://github.com/matrix-org/matrix-spec/issues/1444))
- Endpoint disclosures now hide everything but the URL. ([#1446](https://github.com/matrix-org/matrix-spec/issues/1446))
- Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. ([#1457](https://github.com/matrix-org/matrix-spec/issues/1457))
- Minor cleanups to the GitHub Actions workflows ([#1476](https://github.com/matrix-org/matrix-spec/issues/1476))
- Fix generation of anchors for additional properties. ([#1488](https://github.com/matrix-org/matrix-spec/issues/1488))
- Fix various typos throughout the specification. ([#1534](https://github.com/matrix-org/matrix-spec/issues/1534))
- Document more of the spec release timeline/process. ([#1538](https://github.com/matrix-org/matrix-spec/issues/1538))

49
content/client-server-api/_index.md
View file

@ -22,11 +22,12 @@ recommended outside test environments.
Clients are authenticated using opaque `access_token` strings (see [Client
Authentication](#client-authentication) for details).
All `POST` and `PUT` endpoints, with the exception of
[`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload), require the
client to supply a request body containing a (potentially empty) JSON object.
Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies,
but this is not required.
All `POST` and `PUT` endpoints, with the exception of [`POST
/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT
/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid),
require the client to supply a request body containing a (potentially empty)
JSON object. Clients should supply a `Content-Type` header of
`application/json` for all requests with JSON bodies, but this is not required.
Similarly, all endpoints require the server to return a JSON object,
with the exception of 200 responses to
@ -61,7 +62,7 @@ error message e.g. `M_FORBIDDEN`. Error codes should have their namespace
first in ALL CAPS, followed by a single `_`. For example, if there was a custom
namespace `com.mydomain.here`, and a `FORBIDDEN` code, the error code should
look like `COM.MYDOMAIN.HERE_FORBIDDEN`. Error codes defined by this
specification should start `M_`.
specification should start with `M_`.
Some `errcode`s define additional keys which should be present in the error
response object, but the keys `error` and `errcode` MUST always be present.
@ -236,19 +237,32 @@ For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`
would return a `200 OK` with the `event_id` of the original request in
the response body.
As well as the HTTP path, the scope of a transaction ID is a "client
session", where that session is identified by a particular access token.
When [refreshing](#refreshing-access-tokens) an access token, the
transaction ID's scope is retained. This means that if a client with
token `A` uses `TXN1` as their transaction ID, refreshes the token to
`B`, and uses `TXN1` again it'll be assumed to be a duplicate request
and ignored. If the client logs out and back in between the `A` and `B`
tokens, `TXN1` could be used once for each.
The scope of a transaction ID is for a single [device](../index.html#devices),
and a single HTTP endpoint. In other words: a single device could use the same
transaction ID for a request to [`PUT
/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid)
and [`PUT
/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid),
and the two requests would be considered distinct because the two are
considered separate endpoints. Similarly, if a client logs out and back in
between two requests using the same transaction ID, the requests are distinct
because the act of logging in and out creates a new device (unless an existing
`device_id` is passed to [`POST
/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a
client re-uses a transaction ID for the same endpoint after
[refreshing](#refreshing-access-tokens) an access token, it will be assumed to
be a duplicate request and ignored. See also
[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices).
Some API endpoints may allow or require the use of `POST` requests
without a transaction ID. Where this is optional, the use of a `PUT`
request is strongly recommended.
{{% boxes/rationale %}}
Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than
devices.
{{% /boxes/rationale %}}
## Web Browser Clients
It is realistic to expect that some clients will be written to be run
@ -1162,8 +1176,14 @@ client supports it, the client should redirect the user to the
is complete, the client will need to submit a `/login` request matching
`m.login.token`.
{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
a token for their user ID if supported by the homeserver using
[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
{{% http-api spec="client-server" api="login" %}}
{{% http-api spec="client-server" api="login_token" %}}
{{% http-api spec="client-server" api="refresh" %}}
{{% http-api spec="client-server" api="logout" %}}
@ -2670,4 +2690,3 @@ systems.
{{< cs-module name="event_annotations" >}}
{{< cs-module name="threading" >}}
{{< cs-module name="reference_relations" >}}

59
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -134,8 +134,7 @@ are offline/unable to upload additional keys, though sessions started using
fallback keys could be vulnerable to replay attacks.
{{% /boxes/warning %}}
Devices will be informed, [via
`/sync`](#a-namee2e-extensions-to-sync-extensions-to-sync), about the number of
Devices will be informed, [via `/sync`](#e2e-extensions-to-sync), about the number of
one-time keys remaining that can be claimed, as well as whether the fallback
keys have been used. The device can thus ensure that, while it is online, there
is a sufficient supply of one-time keys available, and that the fallback keys
@ -306,7 +305,7 @@ properties.
| key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. |
| iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
| v | string | **Required.** Version of the encrypted attachments protocol. Must be `v2`. |
| v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. |
`JWK`
@ -777,33 +776,37 @@ The method used to calculate these MACs depends upon the value of the
message. All current implementations should use the `hkdf-hmac-sha256.v2` method which is
defined as follows:
The MAC used is HMAC as defined in [RFC
5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
function. The shared secret is supplied as the input keying material. No salt
is used, and in the info parameter is the concatenation of:
1. An HMAC key is generated using HKDF, as defined in [RFC
5869](https://tools.ietf.org/html/rfc5869), using SHA-256 as the hash
function. The shared secret is supplied as the input keying material. No salt
is used, and in the info parameter is the concatenation of:
- The string `MATRIX_KEY_VERIFICATION_MAC`.
- The Matrix ID of the user whose key is being MAC-ed.
- The Device ID of the device sending the MAC.
- The Matrix ID of the other user.
- The Device ID of the device receiving the MAC.
- The `transaction_id` being used.
- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
item being MAC-ed is the list of key IDs.
- The string `MATRIX_KEY_VERIFICATION_MAC`.
- The Matrix ID of the user whose key is being MAC-ed.
- The Device ID of the device sending the MAC.
- The Matrix ID of the other user.
- The Device ID of the device receiving the MAC.
- The `transaction_id` being used.
- The Key ID of the key being MAC-ed, or the string `KEY_IDS` if the
item being MAC-ed is the list of key IDs.
If a key is being MACed, the MAC is performed on the public key as encoded
according to the [key algorithm](#key-algorithms). For example, for `ed25519`
keys, it is the unpadded base64-encoded key.
2. A MAC is then generated using HMAC as defined in [RFC
2104](https://tools.ietf.org/html/rfc2104) with the key generated above and
using SHA-256 as the hash function.
If the key list is being MACed, the list is sorted lexicographically and
comma-separated with no extra whitespace added, with each key written in the
form `{algorithm}:{keyId}`. For example, the key list could look like:
`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
reconstruct the list from the names in the `mac` property of the
`m.key.verification.mac` message and ensure that no keys were added or removed.
If a key is being MACed, the MAC is performed on the public key as encoded
according to the [key algorithm](#key-algorithms). For example, for `ed25519`
keys, it is the unpadded base64-encoded key.
The MAC values are base64-encoded and sent in a
[`m.key.verification.mac`](#mkeyverificationmac) message.
If the key list is being MACed, the list is sorted lexicographically and
comma-separated with no extra whitespace added, with each key written in the
form `{algorithm}:{keyId}`. For example, the key list could look like:
`ed25519:Cross+Signing+Key,ed25519:DEVICEID`. In this way, the recipient can
reconstruct the list from the names in the `mac` property of the
`m.key.verification.mac` message and ensure that no keys were added or removed.
3. The MAC values are base64-encoded and sent in a
[`m.key.verification.mac`](#mkeyverificationmac) message.
{{% boxes/note %}}
The MAC method `hkdf-hmac-sha256` used an incorrect base64 encoding, due to a
@ -892,7 +895,7 @@ following table to get the corresponding emoji:
{{% boxes/note %}}
This table is available as JSON at
<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json>
<https://github.com/matrix-org/matrix-spec/blob/main/data-definitions/sas-emoji.json>.
{{% /boxes/note %}}
{{% boxes/rationale %}}
@ -1699,7 +1702,7 @@ When a client is updating a Megolm session in its store, the client MUST ensure:
{{% http-api spec="client-server" api="keys" %}}
##### <a name="e2e-extensions-to-sync"> Extensions to /sync
##### Extensions to /sync {#e2e-extensions-to-sync}
This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientv3sync) response,
as specified below. The server need only populate this property for an

6
content/client-server-api/modules/event_annotations.md
View file

@ -71,6 +71,12 @@ change their reaction, the original reaction should be redacted and a new one
sent in its place.
{{% /boxes/note %}}
{{% boxes/note %}}
The `key` field in `m.reaction` can be any string so clients must take care to
render long reactions in a sensible manner. For example, clients can elide
overly-long reactions.
{{% /boxes/note %}}
#### Server behaviour
##### Avoiding duplicate annotations

71
content/client-server-api/modules/event_replacements.md
View file

@ -249,14 +249,14 @@ events](#redactions-of-edited-events) below.
**Note:** the `content` of the original event is left intact. In particular servers
should **not** replace the content with that of the replacement event.
{{ boxes/rationale }}
{{% boxes/rationale %}}
In previous versions of the specification, servers were expected to replace the
content of an edited event whenever it was served to clients (with the
exception of the
[`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid)
endpoint). However, that behaviour made reliable client-side implementation
difficult, and servers should no longer make this replacement.
{{ /boxes/rationale }}
{{% /boxes/rationale %}}
#### Client behaviour
@ -293,6 +293,73 @@ events will not be included in the aggregation bundled with the original
event. Note that the subsequent edits are not actually redacted themselves:
they simply serve no purpose within the visible timeline.
#### Edits of events with mentions
When editing an event with [user and room mentions](#user-and-room-mentions) the
replacement event will have two `m.mentions` properties:
* One at the top-level of the `content`, which should contain mentions due to
this edit revision.
* One inside the `m.new_content` property, which should contain the resolved mentions
for the final version of the event.
The difference between these properties ensures that users will not be notified
for each edit revision of an event, but allows for new users to be mentioned (or
for re-notifying if the sending client feels a large enough revision was made).
For example, if there is an event mentioning Alice:
```json5
{
"event_id": "$original_event",
"type": "m.room.message",
"content": {
"body": "Hello Alice!",
"m.mentions": {
"user_ids": ["@alice:example.org"]
}
}
}
```
And an edit to also mention Bob:
```json5
{
"content": {
"body": "* Hello Alice & Bob!",
"m.mentions": {
"user_ids": [
// Include only the newly mentioned user.
"@bob:example.org"
]
},
"m.new_content": {
"body": "Hello Alice & Bob!",
"m.mentions": {
"user_ids": [
// Include all of the mentioned users.
"@alice:example.org",
"@bob:example.org"
]
},
},
"m.relates_to": {
"rel_type": "m.replace",
"event_id": "$original_event"
}
},
// other fields as required by events
}
```
If an edit revision removes a user's mention then that user's Matrix ID should be
included in neither `m.mentions` property.
Clients may also wish to modify the [client behaviour](#user-and-room-mentions) of
determining if an event mentions the current user by checking the `m.mentions`
property under `m.new_content`.
#### Edits of replies
Some particular constraints apply to events which replace a

81
content/client-server-api/modules/mentions.md
View file

@ -1,61 +1,76 @@
### User and room mentions
This module allows users to mention other users and rooms within a room message.
This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of
an [m.room.message](#mroommessage) event. This module does not have any server-specific
behaviour to it.
{{% changed-in v="1.7" %}}
Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
`org.matrix.custom.html` and therefore requires a `formatted_body`.
This module allows users to "mention" other users and rooms within a room event.
This is primarily used as an indicator that the recipient should receive a notification
about the event.
This is achieved by including metadata in the `m.mentions` content property of
the event to reference the entity being mentioned.
To make a mention, reference the entity being mentioned in the
`formatted_body` using an anchor, like so:
`m.mentions` is defined as follows:
```json
{
"body": "Hello Alice!",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
}
```
{{% definition path="api/client-server/definitions/m.mentions" %}}
Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
Users should not add their own Matrix ID to the `m.mentions` property as outgoing
messages cannot self-notify.
{{% boxes/warning %}}
If an encrypted event contains an `m.mentions` in its payload, it should be
encrypted as normal. To properly process mentions in encrypted rooms, events
must be decrypted first. See [receiving notifications](#receiving-notifications).
{{% /boxes/warning %}}
Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of
the event contains the user's display name or ID. To avoid unintentional notifications,
**it is recommended that clients include a `m.mentions` property on each event**.
(If there are no mentions to include it can be an empty object.)
{{% boxes/rationale %}}
In previous versions of the specification, mentioning users was done by
including the user's display name or the localpart of their Matrix ID and room
mentions were done by including the string "@room" in the plaintext `body` of
the event. This was prone to confusing and buggy behaviour.
{{% /boxes/rationale %}}
#### Client behaviour
In addition to using the appropriate `Matrix URI` for the mention,
clients should use the following guidelines when making mentions in
events to be sent:
Although it is possible to silently mention users, it is recommended to include a
[Matrix URI](/appendices/#uris) in the HTML body of an [m.room.message](#mroommessage)
event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
`org.matrix.custom.html` and therefore requires a `formatted_body`.
- When mentioning users, use the user's potentially ambiguous display
Clients should use the following guidelines when adding a `Matrix URI`
representing a mention to events to be sent:
- When linking to users, use the user's potentially ambiguous display
name for the anchor's text. If the user does not have a display
name, use the user's ID.
- When mentioning rooms, use the canonical alias for the room. If the
- When linking to rooms, use the canonical alias for the room. If the
room does not have a canonical alias, prefer one of the aliases
listed on the room. If no alias can be found, fall back to the room
ID. In all cases, use the alias/room ID being linked to as the
anchor's text.
The text component of the anchor should be used in the event's `body`
where the mention would normally be represented, as shown in the example
where the link would normally be represented, as shown in the example
above.
Clients should display mentions differently from other elements. For
example, this may be done by changing the background color of the
mention to indicate that it is different from a normal link.
If the current user is mentioned in a message (either by a mention as
defined in this module or by a push rule), the client should show that
If the current user is mentioned in a message, the client should show that
mention differently from other mentions, such as by using a red
background color to signify to the user that they were mentioned.
background color to signify to the user that they were mentioned. Note that
it is possible for a user to be mentioned without including their `Matrix URI`
in the event.
When clicked, the mention should navigate the user to the appropriate
user or room information.
{{% boxes/note %}}
Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
groups used to be representable by mentions. They follow a similar format
to room mentions, though using the group ID in both the link and anchor
text.
{{% /boxes/note %}}

120
content/client-server-api/modules/push.md
View file

@ -147,17 +147,6 @@ actions are defined:
: This causes each matching event to generate a notification.
`dont_notify`
: This prevents each matching event from generating a notification.
`coalesce`
: This enables notifications for matching events but activates homeserver
specific behaviour to intelligently coalesce multiple events into a
single notification. Not all homeservers may support this. Those that do
not support it should treat it as the `notify` action.
`set_tweak`
: Sets an entry in the `tweaks` dictionary key that is sent in the
@ -195,6 +184,12 @@ they are represented as a dictionary with a key equal to their name and
other keys as their parameters, e.g.
`{ "set_tweak": "sound", "value": "default" }`.
{{% boxes/note %}}
Older versions of the Matrix specification included the `dont_notify` and
`coalesce` actions. These should both be considered no-ops (ignored, not
rejected) if received from a client.
{{% /boxes/note %}}
##### Conditions
`override` and `underride` rules MAY have a list of 'conditions'. All
@ -440,9 +435,7 @@ Definition:
"default": true,
"enabled": false,
"conditions": [],
"actions": [
"dont_notify"
]
"actions": []
}
```
@ -464,9 +457,7 @@ Definition:
"pattern": "m.notice",
}
],
"actions": [
"dont_notify",
]
"actions": []
}
```
@ -526,13 +517,50 @@ Definition:
"pattern": "m.room.member"
}
],
"actions": []
}
```
<a id="_m_rule_is_user_mention"/> **`.m.rule.is_user_mention`**
{{< added-in v="1.7" >}}
Matches any message which contains the user's Matrix ID in the list of `user_ids`
under the `m.mentions` property.
Definition:
```json
{
"rule_id": ".m.rule.is_user_mention",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_property_contains",
"key": "content.m\\.mentions.user_ids",
"value": "[the user's Matrix ID]"
}
],
"actions": [
"dont_notify"
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
]
}
```
**`.m.rule.contains_display_name`**
<a id="_m_rule_contains_display_name"/> **`.m.rule.contains_display_name`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message whose content contains the user's current display name
in the room in which it was sent.
@ -562,7 +590,46 @@ Definition:
}
```
**`.m.rule.roomnotif`**
<a id="_m_rule_is_room_mention"/> **`.m.rule.is_room_mention`**
{{< added-in v="1.7" >}}
Matches any message from a sender with the proper power level with the `room`
property of the `m.mentions` property set to `true`.
Definition:
```json
{
"rule_id": ".m.rule.is_room_mention",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_property_is",
"key": "content.m\\.mentions.room",
"value": true
},
{
"kind": "sender_notification_permission",
"key": "room"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight"
}
]
}
```
<a id="_m_rule_roomnotif"/> **`.m.rule.roomnotif`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message from a sender with the proper power level whose content
contains the text `@room`, signifying the whole room should be notified of
@ -633,7 +700,7 @@ Definition:
{{% added-in v="1.7" %}}
Matches any event whose type is `m.room.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events.
Matches any event whose type is `m.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events.
Definition:
@ -685,7 +752,12 @@ Definition:
##### Default Content Rules
**`.m.rule.contains_user_name`**
<a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
{{% changed-in v="1.7" %}}
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.
Matches any message whose content contains the local part of the user's
Matrix ID, separated by word boundaries.
@ -882,14 +954,14 @@ To create a rule that suppresses notifications for the room with ID
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
'{
"actions" : ["dont_notify"]
"actions" : []
}'
To suppress notifications for the user `@spambot:matrix.org`:
curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/v3/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
'{
"actions" : ["dont_notify"]
"actions" : []
}'
To always notify for messages that contain the work 'cake' and set a

6
content/client-server-api/modules/receipts.md
View file

@ -153,12 +153,6 @@ relationships and solid lines showing topological ordering.
![threaded-dag](/diagrams/threaded-dag.png)
{{% boxes/note %}}
`m.reaction` relationships are not currently specified, but are shown here for
their conceptual place in a threaded DAG. They are currently proposed as
[MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677).
{{% /boxes/note %}}
This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread
roots:

32
content/client-server-api/modules/rich_replies.md
View file

@ -176,4 +176,34 @@ This is where the reply goes.
For `m.image`, the text should be `"sent an image."`. For `m.video`, the
text should be `"sent a video."`. For `m.audio`, the text should be
`"sent an audio file"`.
`"sent an audio file"`.
#### Mentioning the replied to user
In order to notify users of the reply, it may be desirable to include the `sender`
of the replied to event and any users mentioned in that event. See
[user and room mentions](#user-and-room-mentions) for additional information.
An example including mentioning the original sender and other users:
```json5
{
"content": {
"m.relates_to": {
"m.in_reply_to": {
"event_id": "$another_event"
}
},
"body": "That sounds like a great idea!",
"m.mentions": {
"user_ids": [
// The sender of $another_event.
"@alice:example.org",
// Another Matrix ID copied from the m.mentions property of $another_event.
"@bob:example.org"
]
}
},
// other fields as required by events
}
```

159
content/client-server-api/modules/voip_events.md
View file

@ -6,11 +6,128 @@ This module outlines how two users in a room can set up a Voice over IP
WebRTC 1.0 standard. Call signalling is achieved by sending [message
events](#events) to the room. In this version of the spec, only two-party
communication is supported (e.g. between two peers, or between a peer
and a multi-point conferencing unit). This means that clients MUST only
send call events to rooms with exactly two participants.
and a multi-point conferencing unit). Calls can take place in rooms with
multiple members, but only two devices can take part in the call.
All VoIP events have a `version` field. This is used to determine whether
devices support this new version of the protocol. For example, clients can use
this field to know whether to expect an `m.call.select_answer` event from their
opponent. If clients see events with `version` other than `0` or `"1"`
(including, for example, the numeric value `1`), they should treat these the
same as if they had `version` == `"1"`.
Note that this implies any and all future versions of VoIP events should be
backwards-compatible. If it does become necessary to introduce a non
backwards-compatible VoIP spec, the intention would be for it to simply use a
separate set of event types.
#### Party Identifiers
Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the
duration of the call. This needs to be long enough that the chance of a collision between multiple devices
both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase +
lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of
`(user_id, party_id)`.
The client adds a `party_id` field containing this ID to the top-level of the content of all VoIP events
it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own
events: since a user may call themselves, they cannot simply ignore events from their own user. This
field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates`
events to their respective answer/invite.
A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose,
or it may choose, for example, to use a different one for each call to avoid leaking information on which
devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to
send signalling for more than one call party.
A grammar for `party_id` is defined [below](#grammar-for-voip-ids).
#### Politeness
In line with [WebRTC perfect negotiation](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example)
there are rules to establish which party is polite in the process of renegotiation. The callee is
always the polite party. In a glare situation, the politeness of a party is therefore determined by
whether the inbound or outbound call is used: if a client discards its outbound call in favour of
an inbound call, it becomes the polite party.
#### Call Event Liveness
`m.call.invite` contains a `lifetime` field that indicates how long the offer is valid for. When
a client receives an invite, it should use the event's `age` field in the sync response plus the
time since it received the event from the homeserver to determine whether the invite is still valid.
The use of the `age` field ensures that incorrect clocks on client devices don't break calls.
If the invite is still valid *and will remain valid for long enough for the user to accept the call*,
it should signal an incoming call. The amount of time allowed for the user to accept the call may
vary between clients. For example, it may be longer on a locked mobile device than on an unlocked
desktop device.
The client should only signal an incoming call in a given room once it has completed processing the
entire sync response and, for encrypted rooms, attempted to decrypt all encrypted events in the
sync response for that room. This ensures that if the sync response contains subsequent events that
indicate the call has been hung up, rejected, or answered elsewhere, the client does not signal it.
If on startup, after processing locally stored events, the client determines that there is an invite
that is still valid, it should still signal it but only after it has completed a sync from the homeserver.
The minimal recommended lifetime is 90 seconds - this should give the user enough time to actually pick
up the call.
#### ICE Candidate Batching
Clients should aim to send a small number of candidate events, with guidelines:
* ICE candidates which can be discovered immediately or almost immediately in the invite/answer
event itself (eg. host candidates). If server reflexive or relay candidates can be gathered in
a sufficiently short period of time, these should be sent here too. A delay of around 200ms is
suggested as a starting point.
* The client should then allow some time for further candidates to be gathered in order to batch them,
rather than sending each candidate as it arrives. A starting point of 2 seconds after sending the
invite or 500ms after sending the answer is suggested as a starting point (since a delay is natural
anyway after the invite whilst the client waits for the user to accept it).
#### End-of-candidates
An ICE candidate whose value is the empty string means that no more ICE candidates will
be sent. Clients must send such a candidate in an `m.call.candidates` message.
The WebRTC spec requires browsers to generate such a candidate, however note that at time of writing,
not all browsers do (Chrome does not, but does generate an `icegatheringstatechange` event). The
client should send any remaining candidates once candidate generation finishes, ignoring timeouts above.
This allows bridges to batch the candidates together when bridging to protocols that don't support
trickle ICE.
#### DTMF
Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of August
2020 does not support receiving DTMF but a Matrix client can receive and interpret the DTMF sent
in the RTP payload.
#### Grammar for VoIP IDs
`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
of the characters `[0-9a-zA-Z._~-]`.
(Note that this matches the grammar of 'opaque IDs' from
[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
and that of the `id` property of the
[`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
#### Behaviour on Room Leave
If the client sees the user it is in a call with leave the room, the client should treat this
as a hangup event for any calls that are in progress. No specific requirement is given for the
situation where a client has sent an invite and the invitee leaves the room, but the client may
wish to treat it as a rejection if there are no more users in the room who could answer the call
(eg. the user is now alone or the `invitee` field was set on the invite).
The same behaviour applies when a client is looking at historic calls.
#### Supported Codecs
The Matrix spec does not mandate particular audio or video codecs, but instead defers to the
WebRTC spec. A compliant Matrix VoIP client will behave in the same way as a supported 'browser'
in terms of what codecs it supports and what variants thereof. The latest WebRTC specification
applies, so clients should keep up to date with new versions of the WebRTC specification whether
or not there have been any changes to the Matrix spec.
#### Events
##### Common Fields
{{% event-fields event_type="call_event" %}}
##### Events
{{% event-group group_name="m.call" %}}
#### Client behaviour
@ -25,6 +142,7 @@ A call is set up with message events exchanged as follows:
[..candidates..] -------->
[Answers call]
<--------------- m.call.answer
m.call.select_answer ----------->
[Call is active and ongoing]
<--------------- m.call.hangup
```
@ -42,6 +160,43 @@ Or a rejected call:
Calls are negotiated according to the WebRTC specification.
In response to an incoming invite, a client may do one of several things:
* Attempt to accept the call by sending an `m.call.answer`.
* Actively reject the call everywhere: send an `m.call.reject` as per above, which will stop the call from
ringing on all the user's devices and the caller's client will inform them that the user has
rejected their call.
* Ignore the call: send no events, but stop alerting the user about the call. The user's other
devices will continue to ring, and the caller's device will continue to indicate that the call
is ringing, and will time the call out in the normal way if no other device responds.
##### Streams
Clients are expected to send one stream with one track of kind `audio` (creating a
voice call). They can optionally send a second track in the same stream of kind
`video` (creating a video call).
Clients implementing this specification use the first stream and will ignore
any streamless tracks. Note that in the JavaScript WebRTC API, this means
`addTrack()` must be passed two parameters: a track and a stream, not just a
track, and in a video call the stream must be the same for both audio and video
track.
A client may send other streams and tracks but the behaviour of the other party
with respect to presenting such streams and tracks is undefined.
##### Invitees
The `invitee` field should be added whenever the call is intended for one
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
annotate that it was ignored.
##### Glare
"Glare" is a problem which occurs when two users call each other at

5
content/server-server-api.md
View file

@ -877,8 +877,7 @@ on the resulting `m.room.member` event.
If the joining server fails all conditions then a 403 `M_FORBIDDEN` error
is used by the resident server.
<a name="knocking-rooms">
## Knocking upon a room
## Knocking upon a room {#knocking-rooms}
Rooms can permit knocking through the join rules, and if permitted this
gives users a way to request to join (be invited) to the room. Users who
@ -1270,7 +1269,7 @@ specification](/rooms) for more information. It is
calculated as follows.
1. The event is put through the redaction algorithm.
2. The `signatures`, `age_ts`, and `unsigned` properties are removed
2. The `signatures` and `unsigned` properties are removed
from the event, if present.
3. The event is converted into [Canonical
JSON](/appendices#canonical-json).

72
data/api/application-service/ping.yaml Normal file
View file

@ -0,0 +1,72 @@
# Copyright 2023 Tulir Asokan
#
# 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.
openapi: 3.1.0
info:
title: Matrix Application Service API
version: 1.0.0
paths:
/ping:
post:
x-addedInMatrixVersion: "1.7"
summary: Ping the application service
description: |-
This API is called by the homeserver to ensure that the connection works
and the `hs_token` the homeserver has is correct.
Currently this is only called by the homeserver as a direct result of
the application service calling
[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
operationId: ping
security:
- homeserverAccessToken: []
requestBody:
content:
application/json:
schema:
type: object
example: {
"transaction_id": "mautrix-go_1683636478256400935_123"
}
properties:
transaction_id:
type: string
description: |-
A transaction ID for the ping, copied directly from the
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
description: Ping body with optional transaction ID.
responses:
"200":
description: The provided `hs_token` is valid and the ping request was successful.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

405
data/api/application-service/protocols.yaml
View file

@ -11,25 +11,15 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Application Service API
version: 1.0.0
paths:
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
summary: Retrieve metadata about a specific protocol that the application
service supports.
description: |-
This API is called by the homeserver when it wants to present clients
with specific information about the various third-party networks that
@ -40,42 +30,53 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
example: irc
schema:
$ref: definitions/protocol.yaml
401:
type: string
responses:
"200":
description: The protocol was found and metadata returned.
content:
application/json:
schema:
$ref: definitions/protocol.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third-party user.
@ -89,102 +90,130 @@ paths:
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
example: irc
schema:
type: string
- in: query
name: fields...
type: string
name: fields
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: definitions/user_batch.yaml
401:
type: object
additionalProperties:
type: string
responses:
"200":
description: The Matrix User IDs found with the given parameters.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portal rooms leading to a third-party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third-party location.
description: Retrieve a list of Matrix portal rooms that lead to the matched
third-party location.
operationId: queryLocationByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
example: irc
schema:
type: string
- in: query
name: fields...
type: string
name: fields
description: |-
One or more custom fields that are passed to the application
service to help identify the third-party location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: definitions/location_batch.yaml
401:
type: object
additionalProperties:
type: string
responses:
"200":
description: At least one portal room was found.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/thirdparty/location:
get:
summary: Reverse-lookup third-party locations given a Matrix room alias.
description: |-
@ -196,84 +225,118 @@ paths:
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
responses:
200:
description: |-
All found third-party locations.
schema:
$ref: definitions/location_batch.yaml
401:
type: string
responses:
"200":
description: All found third-party locations.
content:
application/json:
schema:
$ref: definitions/location_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
/thirdparty/user:
get:
summary: Reverse-lookup third-party users given a Matrix User ID.
description: |-
Retrieve an array of third-party users from a Matrix User ID.
description: Retrieve an array of third-party users from a Matrix User ID.
operationId: queryUserByID
security:
- homeserverAccessToken: []
parameters:
- in: query
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
responses:
200:
description: |-
An array of third-party users.
schema:
$ref: definitions/user_batch.yaml
401:
type: string
responses:
"200":
description: An array of third-party users.
content:
application/json:
schema:
$ref: definitions/user_batch.yaml
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"404":
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

104
data/api/application-service/query_room.yaml
View file

@ -12,21 +12,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Application Service API
version: 1.0.0
paths:
"/rooms/{roomAlias}":
get:
@ -43,48 +32,75 @@ paths:
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
example: "#magicforest:example.com"
schema:
type: string
responses:
200:
"200":
description: |-
The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set
before responding.
examples:
application/json: {}
schema:
type: object
401:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

104
data/api/application-service/query_user.yaml
View file

@ -12,21 +12,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Application Service API
version: 1.0.0
paths:
"/users/{userId}":
get:
@ -43,45 +32,72 @@ paths:
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
responses:
200:
"200":
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
examples:
application/json: {}
schema:
type: object
401:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"403":
description: The credentials supplied by the homeserver were rejected.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

89
data/api/application-service/transactions.yaml
View file

@ -12,19 +12,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Application Service API
version: 1.0.0
paths:
"/transactions/{txnId}":
put:
@ -42,35 +33,59 @@ paths:
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: Transaction information
example: "35"
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member.yaml"},
{"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
]
}
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
$ref: "../client-server/definitions/client_event.yaml"
required: ["events"]
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"events": [
{
"$ref": "../../event-schemas/examples/m.room.member.yaml"
},
{
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
}
]
}
properties:
events:
type: array
description: A list of events, formatted as per the Client-Server API.
items:
$ref: ../client-server/definitions/client_event.yaml
required:
- events
description: Transaction information
responses:
200:
"200":
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/app/v1
components:
securitySchemes:
$ref: definitions/security.yaml

397
data/api/client-server/account-data.yaml
View file

@ -11,21 +11,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Client Config API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Client Config API
version: 1.0.0
paths:
"/user/{userId}/account_data/{type}":
put:
@ -40,71 +29,85 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to set account data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
- in: body
name: content
required: true
description: |-
The content of the account data.
example: org.example.custom.config
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"
}
description: The content of the account data.
required: true
responses:
200:
description:
The account data was successfully added.
examples:
application/json: {}
schema:
type: object
400:
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
The request body is not a JSON object. Errcode: `M_BAD_JSON`
or `M_NOT_JSON`.
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
tags:
- User data
get:
@ -117,51 +120,61 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to get account data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
responses:
200:
description:
The account data content for the given type.
example: org.example.custom.config
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
403:
type: string
responses:
"200":
description: The account data content for the given type.
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"
}
"403":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"404":
description: |-
No account data has been provided for this user with the given `type`.
Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Account data not found."
}
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
@ -176,79 +189,93 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to set account data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to set account data on.
x-example: "!726s6s6q:example.com"
description: The ID of the room to set account data on.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
- in: body
name: content
required: true
description: |-
The content of the account data.
example: org.example.custom.room.config
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"}
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"
}
description: The content of the account data.
required: true
responses:
200:
description:
The account data was successfully added.
examples:
application/json: {}
schema:
type: object
400:
"200":
description: The account data was successfully added.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
The request body is not a JSON object (errcode `M_BAD_JSON` or
`M_NOT_JSON`), or the given `roomID` is not a valid room ID
(errcode `M_INVALID_PARAM`).
examples:
application/json: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_JSON",
"error": "Content must be a JSON object."
}
"403":
description: |-
The access token provided is not authorized to modify this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
405:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"405":
description: |-
This `type` of account data is controlled by the server; it cannot be
modified by clients. Errcode: `M_BAD_JSON`.
examples:
application/json: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_BAD_JSON",
"error": "Cannot set m.fully_read through this API."
}
tags:
- User data
get:
@ -261,65 +288,95 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to get account data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
example: "@alice:example.com"
schema:
type: string
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to get account data for.
x-example: "!726s6s6q:example.com"
description: The ID of the room to get account data for.
example: "!726s6s6q:example.com"
schema:
type: string
- in: path
type: string
name: type
required: true
description: |-
The event type of the account data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
responses:
200:
description:
The account data content for the given type.
example: org.example.custom.room.config
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
400:
description: |-
The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
403:
type: string
responses:
"200":
description: The account data content for the given type.
content:
application/json:
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"
}
"400":
description: "The given `roomID` is not a valid room ID. Errcode:
`M_INVALID_PARAM`."
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PARAM",
"error": "@notaroomid:example.org is not a valid room ID."
}
"403":
description: |-
The access token provided is not authorized to retrieve this user's account
data. Errcode: `M_FORBIDDEN`.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Cannot add account data for other users."
}
"404":
description: |-
No account data has been provided for this user and this room with the
given `type`. Errcode: `M_NOT_FOUND`.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room account data not found."
}
tags:
- User data
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

156
data/api/client-server/admin.yaml
View file

@ -11,21 +11,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Administration API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Administration API
version: 1.0.0
paths:
"/admin/whois/{userId}":
get:
@ -41,75 +30,94 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: The user to look up.
required: true
x-example: "@peter:rabbit.rocks"
example: "@peter:rabbit.rocks"
schema:
type: string
responses:
200:
"200":
description: The lookup was successful.
examples:
application/json: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"connections": [
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one
login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
examples:
response:
value: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
"sessions": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
"connections": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
}
]
}
]
}
]
}
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The Matrix user ID of the user.
devices:
type: object
description: |-
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo
properties:
sessions:
type: array
description: A user's sessions (i.e. what they did with an access token from one login).
items:
type: object
title: SessionInfo
properties:
connections:
type: array
description: Information particular connections in the session.
items:
type: object
title: ConnectionInfo
properties:
ip:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string
description: User agent string last seen in the session.
tags:
- Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

735
data/api/client-server/administrative_contact.yaml
View file

@ -12,23 +12,12 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Account Administrative Contact API
version: 1.0.0
paths:
"/account/3pid":
/account/3pid:
get:
summary: Gets a list of a user's third-party identifiers.
description: |-
@ -44,48 +33,56 @@ paths:
security:
- accessToken: []
responses:
200:
"200":
description: The lookup was successful.
examples:
application/json: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
schema:
type: object
properties:
threepids:
type: array
items:
type: object
title: Third-party identifier
properties:
medium:
type: string
description: The medium of the third-party identifier.
enum: ["email", "msisdn"]
address:
type: string
description: The third-party identifier address.
validated_at:
type: integer
format: int64
description: |-
The timestamp, in milliseconds, when the identifier was
validated by the identity server.
added_at:
type: integer
format: int64
description:
The timestamp, in milliseconds, when the homeserver
associated the third-party identifier with the user.
required: ['medium', 'address', 'validated_at', 'added_at']
content:
application/json:
schema:
type: object
properties:
threepids:
type: array
items:
type: object
title: Third-party identifier
properties:
medium:
type: string
description: The medium of the third-party identifier.
enum:
- email
- msisdn
address:
type: string
description: The third-party identifier address.
validated_at:
type: integer
format: int64
description: |-
The timestamp, in milliseconds, when the identifier was
validated by the identity server.
added_at:
type: integer
format: int64
description: The timestamp, in milliseconds, when the homeserver associated the
third-party identifier with the user.
required:
- medium
- address
- validated_at
- added_at
examples:
response:
value: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
tags:
- Account management
post:
@ -105,36 +102,40 @@ paths:
deprecated: true
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
three_pid_creds:
title: "ThreePidCredentials"
type: object
description: The third-party credentials to associate with the account.
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
required: ["three_pid_creds"]
example: {
requestBody:
content:
application/json:
schema:
type: object
properties:
three_pid_creds:
title: ThreePidCredentials
type: object
description: The third-party credentials to associate with the account.
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required:
- client_secret
- id_server
- id_access_token
- sid
required:
- three_pid_creds
example: {
"three_pid_creds": {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
@ -142,45 +143,52 @@ paths:
"client_secret": "d0nt-T3ll"
}
}
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {
"submit_url": "https://example.org/path/to/submitToken"
}
schema:
type: object
properties:
submit_url:
type: string
format: uri
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's `POST
/validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
content:
application/json:
schema:
type: object
properties:
submit_url:
type: string
format: uri
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's `POST
/validate/email/submitToken` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the `/versions` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
403:
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the `/versions` response (ie: r0.5.0).
example: https://example.org/path/to/submitToken
examples:
response:
value: {
"submit_url": "https://example.org/path/to/submitToken"
}
"403":
description: The credentials could not be verified with the identity server.
examples:
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third-party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third-party credentials could not be verified by the identity server."
}
tags:
- Account management
"/account/3pid/add":
/account/3pid/add:
post:
summary: Adds contact information to the user's account.
description: |-
@ -194,47 +202,55 @@ paths:
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
example: "d0nt-T3ll"
sid:
type: string
description: The session identifier given by the homeserver.
example: "abc123987"
required: ["client_secret", "sid"]
requestBody:
content:
application/json:
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: definitions/auth_data.yaml
client_secret:
type: string
description: The client secret used in the session with the homeserver.
example: d0nt-T3ll
sid:
type: string
description: The session identifier given by the homeserver.
example: abc123987
required:
- client_secret
- sid
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The homeserver requires additional authentication information.
content:
application/json:
schema:
$ref: definitions/auth_response.yaml
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/account/3pid/bind":
/account/3pid/bind:
post:
summary: Binds a 3PID to the user's account through an Identity Service.
description: |-
@ -248,47 +264,55 @@ paths:
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0nt-T3ll"
}
requestBody:
content:
application/json:
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required:
- client_secret
- id_server
- id_access_token
- sid
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0nt-T3ll"
}
required: true
responses:
200:
"200":
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
429:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Account management
"/account/3pid/delete":
/account/3pid/delete:
post:
summary: Deletes a third-party identifier from the user's account
description: |-
@ -301,59 +325,63 @@ paths:
operationId: delete3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
requestBody:
content:
application/json:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The homeserver has disassociated the third-party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. `success` indicates that the
identity server has unbound the identifier whereas `no-support`
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- no-support
- success
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. `success` indicates that the
identity server has unbound the identifier whereas `no-support`
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: success
required:
- id_server_unbind_result
tags:
- Account management
"/account/3pid/unbind":
/account/3pid/unbind:
post:
summary: Removes a user's third-party identifier from an identity server.
description: |-
@ -366,60 +394,65 @@ paths:
operationId: unbind3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
requestBody:
content:
application/json:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the `id_server` the identifier was added through. If the
homeserver does not know the original `id_server`, it MUST return
a `id_server_unbind_result` of `no-support`.
example: "example.org"
medium:
type: string
description: The medium of the third-party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third-party address being removed.
example: "example@example.org"
required: ['medium', 'address']
example: example.org
medium:
type: string
description: The medium of the third-party identifier being removed.
enum:
- email
- msisdn
example: email
address:
type: string
description: The third-party address being removed.
example: example@example.org
required:
- medium
- address
required: true
responses:
200:
"200":
description: |-
The identity server has disassociated the third-party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: "success"
required:
- id_server_unbind_result
content:
application/json:
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- no-support
- success
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. `success` indicates that the identity server has unbound the
identifier whereas `no-support` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: success
required:
- id_server_unbind_result
tags:
- Account management
"/account/3pid/email/requestToken":
/account/3pid/email/requestToken:
post:
summary: Begins the validation process for an email address for association with the user's account.
summary: Begins the validation process for an email address for association with
the user's account.
description: |-
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should
@ -430,49 +463,58 @@ paths:
the email itself, either by sending a validation email itself or by using
a service it has control over.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
required: true
responses:
200:
"200":
description: |-
An email was sent to the given address. Note that this may be an
email containing the validation token or it may be informing the
user of an error.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"400":
description: |-
The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
"/account/3pid/msisdn/requestToken":
/account/3pid/msisdn/requestToken:
post:
summary: Begins the validation process for a phone number for association with the user's account.
summary: Begins the validation process for a phone number for association with
the user's account.
description: |-
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should
@ -483,40 +525,63 @@ paths:
the phone number itself, either by sending a validation message itself or by using
a service it has control over.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
required: true
responses:
200:
"200":
description: An SMS message was sent to the given phone number.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
400:
content:
application/json:
schema:
$ref: definitions/request_token_response.yaml
"400":
description: |-
The third-party identifier is already in use on the homeserver, or
the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third-party identifier already in use"
}
"403":
description: |-
The homeserver does not allow the third-party identifier as a
contact option.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_DENIED",
"error": "Third-party identifier is not allowed"
}
tags:
- Account management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

182
data/api/client-server/appservice_ping.yaml Normal file
View file

@ -0,0 +1,182 @@
# Copyright 2023 Tulir Asokan
#
# 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.
openapi: 3.1.0
info:
title: Matrix Client-Server Application Service Ping API
version: 1.0.0
paths:
"/appservice/{appserviceId}/ping":
post:
x-addedInMatrixVersion: "1.7"
summary: Ask the homeserver to ping the application service to ensure the
connection works.
description: |-
This API asks the homeserver to call the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
application service to ensure that the homeserver can communicate
with the application service.
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
users who are not identified as application services. Additionally, the
appservice ID in the path must be the same as the appservice whose `as_token`
is being used.
operationId: pingAppservice
parameters:
- in: path
name: appserviceId
description: |-
The appservice ID of the appservice to ping. This must be the same
as the appservice whose `as_token` is being used to authenticate the
request.
required: true
example: telegram
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
transaction_id:
type: string
description: An optional transaction ID that is passed through to the
`/_matrix/app/v1/ping` call.
example: mautrix-go_1683636478256400935_123
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
"200":
description: The ping was successful.
content:
application/json:
schema:
type: object
properties:
duration_ms:
type: integer
description: |-
The duration in milliseconds that the
[`/_matrix/app/v1/ping`](#post_matrixappv1ping)
request took from the homeserver's point of view.
required:
- duration_ms
examples:
response:
value: {
"duration_ms": 123
}
"400":
description: The application service doesn't have a URL configured. The errcode
is `M_URL_NOT_SET`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_URL_NOT_SET",
"error": "Application service doesn't have a URL configured"
}
"403":
description: The access token used to authenticate the request doesn't belong to
an appservice, or belongs to a different appservice than the one in
the path. The errcode is `M_FORBIDDEN`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Provided access token is not the appservice's as_token"
}
"502":
description: |-
The application service returned a bad status, or the connection failed.
The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
For bad statuses, the response may include `status` and `body`
fields containing the HTTP status code and response body text
respectively to aid with debugging.
content:
application/json:
schema:
type: object
title: Error
description: A Matrix-level Error
properties:
errcode:
type: string
description: An error code.
enum:
- M_BAD_STATUS
- M_CONNECTION_FAILED
error:
type: string
description: A human-readable error message.
example: Ping returned status 401
status:
type: integer
description: The HTTP status code returned by the appservice.
example: 401
body:
type: string
description: The HTTP response body returned by the appservice.
example: '{"errcode": "M_UNKNOWN_TOKEN"}'
required:
- errcode
examples:
response:
value: {
"errcode": "M_BAD_STATUS",
"error": "Ping returned status 401",
"status": 401,
"body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
}
"504":
description: The connection to the application service timed out. The errcode is
`M_CONNECTION_TIMEOUT`.
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_CONNECTION_TIMEOUT",
"error": "Connection to application service timed out"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

92
data/api/client-server/appservice_room_directory.yaml
View file

@ -11,28 +11,14 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Application Service Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
title: Matrix Client-Server Application Service 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.
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
directory.
@ -46,43 +32,69 @@ paths:
operationId: updateAppserviceRoomDirectoryVisibility
parameters:
- in: path
type: string
name: networkId
description: |-
The protocol (network) ID to update the room list for. This would
have been provided by the application service as being listed as
a supported protocol.
required: true
x-example: "irc"
example: irc
schema:
type: string
- in: path
type: string
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:example.org"
- in: body
name: body
required: true
example: "!somewhere:example.org"
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility:
type: string
enum:
- public
- private
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: public
required:
- visibility
required: true
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
"200":
description: The room's directory visibility has been updated.
schema:
type: object
examples:
application/json: {}
content:
application/json:
schema:
type: object
examples:
response:
value: {}
tags:
- Application service room directory management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml

186
data/api/client-server/banning.yaml
View file

@ -11,21 +11,10 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Room Banning API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Room Banning API
version: 1.0.0
paths:
"/rooms/{roomId}/ban":
post:
@ -41,51 +30,60 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be banned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
example: "!e42d8c:matrix.org"
schema:
type: object
example: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being banned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: The reason the user has been banned. This will be supplied as the
`reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
required: ["user_id"]
properties:
user_id:
type: string
description: The fully qualified user ID of the user being banned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: The reason the user has been banned. This will be supplied as the
`reason` on the target's updated
[`m.room.member`](/client-server-api/#mroommember) event.
required:
- user_id
required: true
responses:
200:
"200":
description: The user has been kicked and banned from the room.
examples:
application/json: {
}
schema:
type: object
403:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"403":
description: |-
You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
tags:
- Room membership
"/rooms/{roomId}/unban":
@ -101,50 +99,74 @@ paths:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be unbanned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
description: The room identifier (not alias) from which the user should be
unbanned.
required: true
example: "!e42d8c:matrix.org"
schema:
type: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "They've been banned long enough"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: {
type: string
requestBody:
content:
application/json:
schema:
type: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "They've been banned long enough"
}
schema:
type: object
403:
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
reason:
x-addedInMatrixVersion: "1.1"
type: string
description: |-
Optional reason to be included as the `reason` on the subsequent
membership event.
required:
- user_id
required: true
responses:
"200":
description: The user has been unbanned from the room.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"403":
description: |-
You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
tags:
- Room membership
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

169
data/api/client-server/capabilities.yaml
View file

@ -11,21 +11,12 @@
# 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.
swagger: '2.0'
openapi: 3.1.0
info:
title: "Matrix Client-Server Capabilities API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
title: Matrix Client-Server Capabilities API
version: 1.0.0
paths:
"/capabilities":
/capabilities:
get:
summary: Gets information about the server's capabilities.
description: |-
@ -34,79 +25,99 @@ paths:
operationId: getCapabilities
security:
- accessToken: []
parameters: []
responses:
200:
description:
The capabilities of the server.
examples:
application/json: {
"capabilities": {
"m.change_password": {
"enabled": false
},
"m.room_versions": {
"default": "1",
"available": {
"1": "stable",
"2": "stable",
"3": "unstable",
"test-version": "unstable"
}
},
"com.example.custom.ratelimit": {
"max_requests_per_hour": 600
}
}
}
schema:
type: object
required: ["capabilities"]
properties:
capabilities:
"200":
description: The capabilities of the server.
content:
application/json:
schema:
type: object
title: Capabilities
description: |-
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
required:
- capabilities
properties:
"m.change_password":
capabilities:
type: object
title: Capabilities
description: |-
Capability to indicate if the user can change their password.
title: ChangePasswordCapability
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
properties:
enabled:
type: boolean
description: |-
True if the user can change their password, false otherwise.
example: false
required: ['enabled']
"m.room_versions":
type: object
description: The room versions the server supports.
title: RoomVersionsCapability
properties:
default:
type: string
description: |-
The default room version the server is using for new rooms.
example: "1"
available:
m.change_password:
type: object
description: |-
A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum: [stable, unstable]
description: The stability of the room version.
required: ['default', 'available']
429:
description: Capability to indicate if the user can change their password.
title: ChangePasswordCapability
properties:
enabled:
type: boolean
description: True if the user can change their password, false otherwise.
example: false
required:
- enabled
m.room_versions:
type: object
description: The room versions the server supports.
title: RoomVersionsCapability
properties:
default:
type: string
description: The default room version the server is using for new rooms.
example: "1"
available:
type: object
description: A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum:
- stable
- unstable
description: The stability of the room version.
required:
- default
- available
examples:
response:
value: {
"capabilities": {
"m.change_password": {
"enabled": false
},
"m.room_versions": {
"default": "1",
"available": {
"1": "stable",
"2": "stable",
"3": "unstable",
"test-version": "unstable"
}
},
"com.example.custom.ratelimit": {
"max_requests_per_hour": 600
}
}
}
"429":
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
content:
application/json:
schema:
$ref: definitions/errors/rate_limited.yaml
tags:
- Capabilities
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v3
components:
securitySchemes:
$ref: definitions/security.yaml

910
data/api/client-server/content-repo.yaml
View file

File diff suppressed because it is too large Load diff

Some files were not shown because too many files have changed in this diff Show more