Merge 3c17aa3789 into 6b5ff04d00

Return main to unstable status
missing comma
2026-03-11 22:14:10 +01:00 · 2025-12-18 18:44:36 +00:00 · 2025-12-18 16:30:28 +00:00 · 2025-12-18 16:07:32 +00:00 · 2025-12-18 15:57:59 +00:00 · 2025-12-18 15:53:35 +00:00
57 changed files with 457 additions and 167 deletions
--- a/assets/scss/_styles_project.scss
+++ b/assets/scss/_styles_project.scss
@ -257,6 +257,69 @@ Custom SCSS for the Matrix spec

 }

+.endpoints-toc {
+  summary {
+    cursor: pointer;
+    font-weight: $font-weight-bold;
+    font-size: 1.05rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .endpoint-list {
+    list-style: none;
+    padding-left: 0;
+    margin: 0;
+  }
+
+  .endpoint-list li {
+    margin: 0.2rem 0;
+  }
+
+  .endpoint-list a {
+    text-decoration: none;
+    color: inherit;
+    padding: 0.05rem 0.25rem;
+    border-radius: 0.2rem;
+
+    &:hover {
+      background-color: $secondary-background;
+    }
+  }
+
+  .endpoint-list .http-api-method {
+    margin-right: 0.35rem;
+    font-weight: $font-weight-bold;
+  }
+
+  .endpoint-path {
+    font-family: $font-family-monospace;
+    color: $secondary;
+  }
+
+  .endpoint-deprecated {
+    color: $danger;
+    font-weight: $font-weight-bold;
+    margin-left: 0.35rem;
+  }
+
+  .endpoint-module {
+    &:not(:first-child) {
+      margin-top: 0.75rem;
+    }
+  }
+
+  .endpoint-module-title {
+    // font-weight: $font-weight-bold;
+    font-size: 1.20rem;
+    margin-bottom: 0.35rem;
+  }
+}
+
+.page-description {
+  margin-bottom: 1rem;
+  color: inherit;
+}
+
 /* Styles for alert boxes */
 .alert {
  &.note {
@ -581,4 +644,4 @@ dd {
  .breadcrumb {
    margin: 0;
  }
-}
+}
--- a/changelogs/application_service/newsfragments/2213.clarification
+++ b/changelogs/application_service/newsfragments/2213.clarification
@ -1 +0,0 @@
-Fix JSON formatting in the "Server admin style permissions" examples.
--- a/changelogs/application_service/newsfragments/2221.feature
+++ b/changelogs/application_service/newsfragments/2221.feature
@ -1 +0,0 @@
-Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
--- a/changelogs/application_service/newsfragments/2267.feature
+++ b/changelogs/application_service/newsfragments/2267.feature
@ -1 +0,0 @@
-Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190).
--- a/changelogs/client_server/newsfragments/2181.clarification
+++ b/changelogs/client_server/newsfragments/2181.clarification
@ -0,0 +1,2 @@
+Clarify that the stripped state in `invite_state` and `knock_state` in `GET /sync` response must
+include the full `m.room.member` event of the user.
--- a/changelogs/client_server/newsfragments/2186.removal
+++ b/changelogs/client_server/newsfragments/2186.removal
@ -1 +0,0 @@
-Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).
--- a/changelogs/client_server/newsfragments/2214.clarification
+++ b/changelogs/client_server/newsfragments/2214.clarification
@ -1 +0,0 @@
-Push rule IDs are globally unique within their kind.
--- a/changelogs/client_server/newsfragments/2215.clarification
+++ b/changelogs/client_server/newsfragments/2215.clarification
@ -1 +0,0 @@
-Don't advertise `creator` field in description of room creation.
--- a/changelogs/client_server/newsfragments/2216.clarification
+++ b/changelogs/client_server/newsfragments/2216.clarification
@ -1 +0,0 @@
-`room_id` is required for peeking via `/_matrix/client/v3/events`.
--- a/changelogs/client_server/newsfragments/2217.clarification
+++ b/changelogs/client_server/newsfragments/2217.clarification
@ -1 +0,0 @@
-The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.
--- a/changelogs/client_server/newsfragments/2221.feature
+++ b/changelogs/client_server/newsfragments/2221.feature
@ -1 +0,0 @@
-Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).
--- a/changelogs/client_server/newsfragments/2223.clarification
+++ b/changelogs/client_server/newsfragments/2223.clarification
@ -1 +0,0 @@
-Add note to each endpoint that uses capability negotiation.
--- a/changelogs/client_server/newsfragments/2224.clarification
+++ b/changelogs/client_server/newsfragments/2224.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2225.clarification
+++ b/changelogs/client_server/newsfragments/2225.clarification
@ -1 +0,0 @@
-Additional OpenGraph properties can be present in URL previews.
--- a/changelogs/client_server/newsfragments/2227.clarification
+++ b/changelogs/client_server/newsfragments/2227.clarification
@ -1 +0,0 @@
-Fix various typos throughout the specification.
--- a/changelogs/client_server/newsfragments/2231.clarification
+++ b/changelogs/client_server/newsfragments/2231.clarification
@ -1 +0,0 @@
-Clarify the special casing of membership events and redactions in power levels.
--- a/changelogs/client_server/newsfragments/2232.clarification
+++ b/changelogs/client_server/newsfragments/2232.clarification
@ -1 +0,0 @@
-`M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code.
--- a/changelogs/client_server/newsfragments/2233.clarification
+++ b/changelogs/client_server/newsfragments/2233.clarification
@ -1 +0,0 @@
-Add `m.login.terms` to enumeration of authentication types.
--- a/changelogs/client_server/newsfragments/2234.feature
+++ b/changelogs/client_server/newsfragments/2234.feature
@ -1 +0,0 @@
-Add the `m.oauth` authentication type for User-Interactive Authentication as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312).
--- a/changelogs/client_server/newsfragments/2240.clarification
+++ b/changelogs/client_server/newsfragments/2240.clarification
@ -1 +0,0 @@
-Clarify how to use `state_after` ahead of declaring full support for its spec version.
--- a/changelogs/client_server/newsfragments/2245.clarification
+++ b/changelogs/client_server/newsfragments/2245.clarification
@ -1 +0,0 @@
-`device_one_time_keys_count` is only optional if no unclaimed one-time keys exist.
--- a/changelogs/client_server/newsfragments/2246.clarification
+++ b/changelogs/client_server/newsfragments/2246.clarification
@ -1 +0,0 @@
-Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users.
--- a/changelogs/client_server/newsfragments/2250.clarification
+++ b/changelogs/client_server/newsfragments/2250.clarification
@ -1 +0,0 @@
-Minor grammatical fix in the Secrets module description.
--- a/changelogs/client_server/newsfragments/2255.clarification
+++ b/changelogs/client_server/newsfragments/2255.clarification
@ -1 +0,0 @@
-Usage of the `event_id_only` format for push notifications is not mandatory.
--- a/changelogs/client_server/newsfragments/2267.feature
+++ b/changelogs/client_server/newsfragments/2267.feature
@ -1 +0,0 @@
-Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190).
--- a/changelogs/internal/newsfragments/2219.clarification
+++ b/changelogs/internal/newsfragments/2219.clarification
@ -1 +0,0 @@
-Swapped icon for X (fka. twitter) to updated logo in footer.
--- a/changelogs/internal/newsfragments/2226.clarification
+++ b/changelogs/internal/newsfragments/2226.clarification
@ -1 +0,0 @@
-Inline Olm & Megolm specifications.
--- a/changelogs/internal/newsfragments/2238.clarification
+++ b/changelogs/internal/newsfragments/2238.clarification
@ -1 +0,0 @@
-Silence failing redocly-cli rule.
--- a/changelogs/internal/newsfragments/2239.clarification
+++ b/changelogs/internal/newsfragments/2239.clarification
@ -1 +0,0 @@
-Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm.
--- a/changelogs/internal/newsfragments/2241.clarification
+++ b/changelogs/internal/newsfragments/2241.clarification
@ -1 +0,0 @@
-Inline Olm & Megolm specifications.
--- a/changelogs/internal/newsfragments/2242.clarification
+++ b/changelogs/internal/newsfragments/2242.clarification
@ -1 +0,0 @@
-Inline Olm & Megolm specifications.
--- a/changelogs/internal/newsfragments/2256.clarification
+++ b/changelogs/internal/newsfragments/2256.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2258.clarification
+++ b/changelogs/internal/newsfragments/2258.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2259.clarification
+++ b/changelogs/internal/newsfragments/2259.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2260.clarification
+++ b/changelogs/internal/newsfragments/2260.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2261.clarification
+++ b/changelogs/internal/newsfragments/2261.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2264.clarification
+++ b/changelogs/internal/newsfragments/2264.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/internal/newsfragments/2268.clarification
+++ b/changelogs/internal/newsfragments/2268.clarification
@ -1 +0,0 @@
-Add version picker in the navbar.
--- a/changelogs/room_versions/newsfragments/2220.clarification
+++ b/changelogs/room_versions/newsfragments/2220.clarification
@ -1 +0,0 @@
-In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room.
--- a/changelogs/room_versions/newsfragments/2249.clarification
+++ b/changelogs/room_versions/newsfragments/2249.clarification
@ -1 +0,0 @@
-In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send.  
--- a/config/_default/hugo.toml
+++ b/config/_default/hugo.toml
@ -75,8 +75,8 @@ status = "unstable"
 current_version_url = "https://spec.matrix.org/latest"
 # The following is used when status = "stable", and is displayed in various UI elements on a released version
 # of the spec.
-# major = "1"
-# minor = "16"
+#major = "1"
+#minor = "17"

 [[params.versions]]
 # We must include this parameter to enable docsy's version picker in the navbar. The picker
--- a/content/application-service-api.md
+++ b/content/application-service-api.md
@ -2,16 +2,14 @@
 title: "Application Service API"
 weight: 30
 type: docs
+description: |
+  The Matrix client-server API and server-server APIs provide a consistent,
+  self-contained federated messaging fabric but leave little room for custom
+  server-side behaviour such as gateways, filters, or extensible hooks. The
+  Application Service API defines a standard way to add this extensible
+  functionality, independent of the underlying homeserver implementation.
 ---

-The Matrix client-server API and server-server APIs provide the means to
-implement a consistent self-contained federated messaging fabric.
-However, they provide limited means of implementing custom server-side
-behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The
-Application Service API (AS API) defines a standard API to allow such
-extensible functionality to be implemented irrespective of the
-underlying homeserver implementation.
-
 ## Application Services

 Application services are passive and can only observe events from the
--- a/content/changelog/v1.17.md
+++ b/content/changelog/v1.17.md
@ -0,0 +1,91 @@
+---
+title: v1.17 Changelog
+linkTitle: v1.17
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-12-18
+---
+
+## Client-Server API
+
+**Removed Endpoints**
+
+- Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). ([#2186](https://github.com/matrix-org/matrix-spec/issues/2186))
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Add the `m.oauth` authentication type for User-Interactive Authentication, as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). ([#2234](https://github.com/matrix-org/matrix-spec/issues/2234))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Push rule IDs are globally unique within their kind. ([#2214](https://github.com/matrix-org/matrix-spec/issues/2214))
+- Don't advertise `creator` field in description of room creation. ([#2215](https://github.com/matrix-org/matrix-spec/issues/2215))
+- `room_id` is required for peeking via `/_matrix/client/v3/events`. ([#2216](https://github.com/matrix-org/matrix-spec/issues/2216))
+- The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment. ([#2217](https://github.com/matrix-org/matrix-spec/issues/2217))
+- Add note to each endpoint that uses capability negotiation. ([#2223](https://github.com/matrix-org/matrix-spec/issues/2223))
+- Additional OpenGraph properties can be present in URL previews. ([#2225](https://github.com/matrix-org/matrix-spec/issues/2225))
+- Clarify the special casing of membership events and redactions in power levels. ([#2231](https://github.com/matrix-org/matrix-spec/issues/2231))
+- `M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code. ([#2232](https://github.com/matrix-org/matrix-spec/issues/2232))
+- Add `m.login.terms` to enumeration of authentication types. ([#2233](https://github.com/matrix-org/matrix-spec/issues/2233))
+- Clarify how to use `state_after` ahead of declaring full support for its spec version. ([#2240](https://github.com/matrix-org/matrix-spec/issues/2240))
+- `device_one_time_keys_count` is only optional if no unclaimed one-time keys exist. ([#2245](https://github.com/matrix-org/matrix-spec/issues/2245))
+- Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users. ([#2246](https://github.com/matrix-org/matrix-spec/issues/2246))
+- Usage of the `event_id_only` format for push notifications is not mandatory. ([#2255](https://github.com/matrix-org/matrix-spec/issues/2255))
+- Fix various typos throughout the specification. ([#2224](https://github.com/matrix-org/matrix-spec/issues/2224), [#2227](https://github.com/matrix-org/matrix-spec/issues/2227), [#2250](https://github.com/matrix-org/matrix-spec/issues/2250))
+
+
+## Server-Server API
+
+No significant changes.
+
+
+## Application Service API
+
+**Backwards Compatible Changes**
+
+- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
+- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
+
+**Spec Clarifications**
+
+- Fix JSON formatting in the "Server admin style permissions" examples. ([#2213](https://github.com/matrix-org/matrix-spec/issues/2213))
+
+
+## Identity Service API
+
+No significant changes.
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+**Spec Clarifications**
+
+- In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room. ([#2220](https://github.com/matrix-org/matrix-spec/issues/2220))
+- In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send. ([#2249](https://github.com/matrix-org/matrix-spec/issues/2249))
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Swapped icon for X (fka. twitter) to updated logo in footer. ([#2219](https://github.com/matrix-org/matrix-spec/issues/2219))
+- Inline Olm & Megolm specifications. ([#2226](https://github.com/matrix-org/matrix-spec/issues/2226), [#2241](https://github.com/matrix-org/matrix-spec/issues/2241), [#2242](https://github.com/matrix-org/matrix-spec/issues/2242))
+- Silence failing redocly-cli rule. ([#2238](https://github.com/matrix-org/matrix-spec/issues/2238))
+- Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm. ([#2239](https://github.com/matrix-org/matrix-spec/issues/2239))
+- Add version picker in the navbar. ([#2256](https://github.com/matrix-org/matrix-spec/issues/2256), [#2258](https://github.com/matrix-org/matrix-spec/issues/2258), [#2259](https://github.com/matrix-org/matrix-spec/issues/2259), [#2260](https://github.com/matrix-org/matrix-spec/issues/2260), [#2261](https://github.com/matrix-org/matrix-spec/issues/2261), [#2264](https://github.com/matrix-org/matrix-spec/issues/2264), [#2268](https://github.com/matrix-org/matrix-spec/issues/2268))
+- Add a list of endpoints to the top of each spec page. ([#2262](https://github.com/matrix-org/matrix-spec/issues/2262))
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@ -2,14 +2,14 @@
 title: "Client-Server API"
 weight: 10
 type: docs
+description: |
+  The client-server API allows clients to send messages, control rooms and
+  synchronise conversation history. It is designed to support both lightweight
+  clients which store no state and lazy-load data from the server as required,
+  as well as heavyweight clients which maintain a full local persistent copy of
+  server state.
 ---

-The client-server API allows clients to
-send messages, control rooms and synchronise conversation history. It is
-designed to support both lightweight clients which store no state and
-lazy-load data from the server as required - as well as heavyweight
-clients which maintain a full local persistent copy of server state.
-
 ## API Standards

 {{% boxes/note %}}
@ -3962,42 +3962,42 @@ operations and run in a resource constrained environment. Like embedded
 applications, they are not intended to be fully-fledged communication
 systems.

-{{% cs-module name="instant_messaging" %}}
-{{% cs-module name="rich_replies" %}}
-{{% cs-module name="voip_events" %}}
-{{% cs-module name="typing_notifications" %}}
-{{% cs-module name="receipts" %}}
-{{% cs-module name="read_markers" %}}
-{{% cs-module name="presence" %}}
-{{% cs-module name="content_repo" %}}
-{{% cs-module name="send_to_device" %}}
-{{% cs-module name="device_management" %}}
-{{% cs-module name="end_to_end_encryption" %}}
-{{% cs-module name="secrets" %}}
-{{% cs-module name="history_visibility" %}}
-{{% cs-module name="push" %}}
-{{% cs-module name="third_party_invites" %}}
-{{% cs-module name="search" %}}
-{{% cs-module name="guest_access" %}}
-{{% cs-module name="room_previews" %}}
-{{% cs-module name="tags" %}}
-{{% cs-module name="account_data" %}}
-{{% cs-module name="admin" %}}
-{{% cs-module name="event_context" %}}
-{{% cs-module name="sso_login" %}}
-{{% cs-module name="dm" %}}
-{{% cs-module name="ignore_users" %}}
-{{% cs-module name="stickers" %}}
-{{% cs-module name="report_content" %}}
-{{% cs-module name="third_party_networks" %}}
-{{% cs-module name="openid" %}}
-{{% cs-module name="server_acls" %}}
-{{% cs-module name="mentions" %}}
-{{% cs-module name="room_upgrades" %}}
-{{% cs-module name="server_notices" %}}
-{{% cs-module name="moderation_policies" %}}
-{{% cs-module name="spaces" %}}
-{{% cs-module name="event_replacements" %}}
-{{% cs-module name="event_annotations" %}}
-{{% cs-module name="threading" %}}
-{{% cs-module name="reference_relations" %}}
+{{% cs-module name="Instant Messaging" filename="instant_messaging" %}}
+{{% cs-module name="Rich replies" filename="rich_replies" %}}
+{{% cs-module name="Voice over IP" filename="voip_events" %}}
+{{% cs-module name="Typing Notifications" filename="typing_notifications" %}}
+{{% cs-module name="Receipts" filename="receipts" %}}
+{{% cs-module name="Read and unread markers" filename="read_markers" %}}
+{{% cs-module name="Presence" filename="presence" %}}
+{{% cs-module name="Content repository" filename="content_repo" %}}
+{{% cs-module name="Send-to-Device messaging" filename="send_to_device" %}}
+{{% cs-module name="Device Management" filename="device_management" %}}
+{{% cs-module name="End-to-End Encryption" filename="end_to_end_encryption" %}}
+{{% cs-module name="Secrets" filename="secrets" %}}
+{{% cs-module name="Room History Visibility" filename="history_visibility" %}}
+{{% cs-module name="Push Notifications" filename="push" %}}
+{{% cs-module name="Third-party invites" filename="third_party_invites" %}}
+{{% cs-module name="Server Side Search" filename="search" %}}
+{{% cs-module name="Guest Access" filename="guest_access" %}}
+{{% cs-module name="Room Previews" filename="room_previews" %}}
+{{% cs-module name="Room Tagging" filename="tags" %}}
+{{% cs-module name="Client Config" filename="account_data" %}}
+{{% cs-module name="Server Administration" filename="admin" %}}
+{{% cs-module name="Event Context" filename="event_context" %}}
+{{% cs-module name="SSO client login/authentication" filename="sso_login" %}}
+{{% cs-module name="Direct Messaging" filename="dm" %}}
+{{% cs-module name="Ignoring Users" filename="ignore_users" %}}
+{{% cs-module name="Sticker Messages" filename="stickers" %}}
+{{% cs-module name="Reporting Content" filename="report_content" %}}
+{{% cs-module name="Third-party Networks" filename="third_party_networks" %}}
+{{% cs-module name="OpenID" filename="openid" %}}
+{{% cs-module name="Server Access Control Lists (ACLs) for rooms" filename="server_acls" %}}
+{{% cs-module name="User and room mentions" filename="mentions" %}}
+{{% cs-module name="Room Upgrades" filename="room_upgrades" %}}
+{{% cs-module name="Server Notices" filename="server_notices" %}}
+{{% cs-module name="Moderation policy lists" filename="moderation_policies" %}}
+{{% cs-module name="Spaces" filename="spaces" %}}
+{{% cs-module name="Event replacements" filename="event_replacements" %}}
+{{% cs-module name="Event annotations and reactions" filename="event_annotations" %}}
+{{% cs-module name="Threading" filename="threading" %}}
+{{% cs-module name="Reference relations" filename="reference_relations" %}}
--- a/content/identity-service-api.md
+++ b/content/identity-service-api.md
@ -2,17 +2,15 @@
 title: "Identity Service API"
 weight: 40
 type: docs
+description: |
+  The Matrix client-server and server-server APIs are largely expressed in
+  Matrix user identifiers. Sometimes it is useful to refer to users by other
+  (“third-party”) identifiers such as email addresses or phone numbers. The
+  Identity Service API describes how mappings between 3PIDs and Matrix user
+  IDs can be established, validated, and used; in practice this has been
+  applied to email addresses and phone numbers.
 ---

-The Matrix client-server and server-server APIs are largely expressed in
-Matrix user identifiers. From time to time, it is useful to refer to
-users by other ("third-party") identifiers, or "3PID"s, e.g. their email
-address or phone number. This Identity Service Specification describes
-how mappings between third-party identifiers and Matrix user identifiers
-can be established, validated, and used. This description technically
-may apply to any 3PID, but in practice has only been applied
-specifically to email addresses and phone numbers.
-
 ## General principles

 The purpose of an identity server is to validate, store, and answer
--- a/content/push-gateway-api.md
+++ b/content/push-gateway-api.md
@ -2,12 +2,11 @@
 title: "Push Gateway API"
 weight: 50
 type: docs
+description: |
+  Clients may want to receive push notifications when events are received at the
+  homeserver. This is managed by a distinct entity called the Push Gateway.
 ---

-Clients may want to receive push notifications when events are received
-at the homeserver. This is managed by a distinct entity called the Push
-Gateway.
-
 ## Overview

 A client's homeserver forwards information about received events to the
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@ -2,49 +2,46 @@
 title: "Server-Server API"
 weight: 20
 type: docs
+description: |
+  Matrix homeservers use the Federation APIs (also known as server-server APIs)
+  to communicate with each other. Homeservers use these APIs to push messages in
+  real-time, retrieve historic messages, and query profile or presence
+  information about users on other servers. The APIs are implemented over HTTPS,
+  with authentication provided by public key signatures both at the TLS
+  transport layer and in HTTP Authorization headers.
+
+  There are three main kinds of communication that occur between
+  homeservers:
+
+  Persistent Data Units (PDUs):
+  These events are broadcast from one homeserver to any others that have
+  joined the same room (identified by Room ID). They are persisted in
+  long-term storage and record the history of messages and state for a
+  room.
+
+  Like email, it is the responsibility of the originating server of a PDU
+  to deliver that event to its recipient servers. However PDUs are signed
+  using the originating server's private key so that it is possible to
+  deliver them through third-party servers.
+
+  Ephemeral Data Units (EDUs):
+  These events are pushed between pairs of homeservers. They are not
+  persisted and are not part of the history of a room, nor does the
+  receiving homeserver have to reply to them.
+
+  Queries:
+  These are single request/response interactions between a given pair of
+  servers, initiated by one side sending an HTTPS GET request to obtain
+  some information, and responded by the other. They are not persisted and
+  contain no long-term significant history. They simply request a snapshot
+  state at the instant the query is made.
+
+  EDUs and PDUs are further wrapped in an envelope called a Transaction,
+  which is transferred from the origin to the destination homeserver using
+  an HTTPS PUT request.
+
 ---

-Matrix homeservers use the Federation APIs (also known as server-server
-APIs) to communicate with each other. Homeservers use these APIs to push
-messages to each other in real-time, to retrieve historic messages from
-each other, and to query profile and presence information about users on
-each other's servers.
-
-The APIs are implemented using HTTPS requests between each of the
-servers. These HTTPS requests are strongly authenticated using public
-key signatures at the TLS transport layer and using public key
-signatures in HTTP Authorization headers at the HTTP layer.
-
-There are three main kinds of communication that occur between
-homeservers:
-
-Persistent Data Units (PDUs):
-These events are broadcast from one homeserver to any others that have
-joined the same room (identified by Room ID). They are persisted in
-long-term storage and record the history of messages and state for a
-room.
-
-Like email, it is the responsibility of the originating server of a PDU
-to deliver that event to its recipient servers. However PDUs are signed
-using the originating server's private key so that it is possible to
-deliver them through third-party servers.
-
-Ephemeral Data Units (EDUs):
-These events are pushed between pairs of homeservers. They are not
-persisted and are not part of the history of a room, nor does the
-receiving homeserver have to reply to them.
-
-Queries:
-These are single request/response interactions between a given pair of
-servers, initiated by one side sending an HTTPS GET request to obtain
-some information, and responded by the other. They are not persisted and
-contain no long-term significant history. They simply request a snapshot
-state at the instant the query is made.
-
-EDUs and PDUs are further wrapped in an envelope called a Transaction,
-which is transferred from the origin to the destination homeserver using
-an HTTPS PUT request.
-
 ## API standards

 The mandatory baseline for server-server communication in Matrix is
--- a/data/api/client-server/sync.yaml
+++ b/data/api/client-server/sync.yaml
@ -374,8 +374,14 @@ paths:
                                    description: |-
                                      The [stripped state events](/client-server-api/#stripped-state) that form the
                                      invite state.
+
+                                      MUST also include the `m.room.member` event of the user with a membership of
+                                      `invite`, and using the same event format as joined rooms with the `event_id`
+                                      and `origin_server_ts` fields.
                                    items:
-                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                      anyOf:
+                                        - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                        - $ref: definitions/client_event_without_room_id.yaml
                                    type: array
                      knock:
                        title: Knocked rooms
@ -399,8 +405,14 @@ paths:
                                    description: |-
                                      The [stripped state events](/client-server-api/#stripped-state) that form the
                                      knock state.
+
+                                      MUST also include the `m.room.member` event of the user with a membership of
+                                      `knock`, and using the same event format as joined rooms with the `event_id` and
+                                      `origin_server_ts` fields.
                                    items:
-                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                      anyOf:
+                                        - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                        - $ref: definitions/client_event_without_room_id.yaml
                                    type: array
                      leave:
                        title: Left rooms
@ -633,6 +645,8 @@ paths:
                                "sender": "@alice:example.com",
                                "type": "m.room.member",
                                "state_key": "@bob:example.com",
+                                "event_id": "$19dl9d3848dJLle:example.com",
+                                "origin_server_ts": 1432735439654,
                                "content": {
                                  "membership": "invite"
                                }
@ -657,6 +671,8 @@ paths:
                                "sender": "@bob:example.com",
                                "type": "m.room.member",
                                "state_key": "@bob:example.com",
+                                "event_id": "$Fg83Kl3764di23a:example.com",
+                                "origin_server_ts": 143273039402,
                                "content": {
                                  "membership": "knock"
                                }
--- a/layouts/_partials/endpoints-toc.html
+++ b/layouts/_partials/endpoints-toc.html
@ -0,0 +1,61 @@
+{{/*
+  
+  Renders a list of API endpoints for the current page, given:
+
+  The outer page's Scratch must contain an "api_endpoints" key, which is either
+  a slice of maps (a list of endpoint metadata dicts) or a map of module name ->
+  slice of endpoint metadata dicts (representing the API modules and the
+  endpoints they each contain). Each endpoint dict must contain the following
+  keys:
+
+    * `anchor`: the HTML anchor for the endpoint
+    * `method`: the HTTP method
+    * `endpoint`: the endpoint path
+    * `summary`: a short summary of the endpoint
+    * `deprecated`: whether the endpoint is deprecated
+    * `module`: the CS API module name, if any, for grouping purposes. If empty,
+      the endpoint is considered "base" or "required".
+  
+*/}}
+
+{{ $raw := .Scratch.Get "api_endpoints" }}
+{{/* Normalize to a slice */}}
+{{ $endpoints := slice }}
+{{ if reflect.IsSlice $raw }}
+  {{ $endpoints = $raw }}
+{{ else if reflect.IsMap $raw }}
+  {{ range $raw }}
+    {{ $endpoints = append $endpoints . }}
+  {{ end }}
+{{ end }}
+{{ if gt (len $endpoints) 0 }}
+  <div class="endpoints-toc mb-4">
+    <details>
+      <summary>List of Endpoints</summary>
+      {{/* Sort by module to group visually */}}
+      {{ $sorted := sort $endpoints "module" }}
+      {{ $current := "" }}
+      {{ range $sorted }}
+        {{ $mod := .module }}
+        {{/* Set a title for the base endpoints */}}
+        {{ if not $mod }}{{ $mod = "Required" }}{{ end }}
+        {{ if ne $mod $current }}
+          {{ if $current }}</ul></div>{{ end }}
+          <div class="endpoint-module">
+            <div class="endpoint-module-title">{{ $mod }}</div>
+            <ul class="endpoint-list">
+          {{ $current = $mod }}
+        {{ end }}
+        {{ $key := printf "%s|%s" .method .anchor }}
+        <li>
+          <a href="#{{ .anchor }}">
+            <span class="http-api-method">{{ .method }}</span>
+            <span class="endpoint-path">{{ .endpoint }}</span>
+            {{ if .deprecated }}<span class="endpoint-deprecated">(deprecated)</span>{{ end }}
+          </a>
+        </li>
+      {{ end }}
+      {{ if $current }}</ul></div>{{ end }}
+    </details>
+  </div>
+{{ end }}
--- a/layouts/_partials/openapi/render-api.html
+++ b/layouts/_partials/openapi/render-api.html
@ -7,6 +7,8 @@
  of each value in `paths` to get a complete URL.
  * `anchor_base`: an optional prefix for the HTML IDs generated by
  this template.
+  * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
+  * `module`: the current CS API module name, if any. Used to group endpoints in the TOC.

  This template replaces the old {{*_http_api}} template.

@ -15,6 +17,8 @@
 {{ $api_data := index .api_data }}
 {{ $base_url := .base_url }}
 {{ $anchor_base := .anchor_base }}
+{{ $page := .page }}
+{{ $module := .module }}

 {{ range $path_name, $path_data := $api_data.paths }}

@ -26,28 +30,28 @@

    {{ with $path_data.get }}

-        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }}
+        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
        {{ partial "openapi/render-operation" $operation_params }}

    {{ end }}

    {{ with $path_data.post }}

-        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }}
+        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
        {{ partial "openapi/render-operation" $operation_params }}

    {{ end }}

    {{ with $path_data.put }}

-        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }}
+        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
        {{ partial "openapi/render-operation" $operation_params }}

    {{ end }}

    {{ with $path_data.delete }}

-        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }}
+        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }}
        {{ partial "openapi/render-operation" $operation_params }}

    {{ end }}
--- a/layouts/_partials/openapi/render-operation.html
+++ b/layouts/_partials/openapi/render-operation.html
@ -7,6 +7,8 @@
  * `operation_data`: the OpenAPI data for the operation
  * `anchor_base`: an optional prefix for the HTML IDs generated by
  this template.
+  * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
+  * `module`: the current CS API module name, if any. Used to group endpoints in the TOC.

  This template renders the operation as a `<section>` containing:

@ -22,6 +24,8 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
+{{ $page := .page }}
+{{ $module := .module }}

 {{ $anchor := "" }}
 {{ if .anchor_base }}
@ -29,6 +33,27 @@
 {{ end }}
 {{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}

+{{/* Collect endpoints for the on-page endpoints TOC */}}
+{{ if $page }}
+  {{/* Store each endpoint's metadata in a scratch variable */}}
+  {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated "module" $module }}
+  {{ if not ($page.Scratch.Get "api_endpoints_seen") }}
+    {{ $page.Scratch.Set "api_endpoints_seen" dict }}
+  {{ end }}
+  {{/* Keep a map of seen endpoints. This is necessary as this partial may be
+       rendered multiple times for the same endpoint (e.g. in the TOC and
+       in the main content), leading to duplicates. */}}
+  {{ $seen := $page.Scratch.Get "api_endpoints_seen" }}
+  {{ $key := printf "%s|%s" $method $endpoint }}
+  {{ if not (index $seen $key) }}
+  {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }}
+    {{ $page.Scratch.Set "api_endpoints" (slice) }}
+  {{ end }}
+  {{ $page.Scratch.Add "api_endpoints" (slice $entry) }}
+    {{ $page.Scratch.SetInMap "api_endpoints_seen" $key true }}
+  {{ end }}
+{{ end }}
+
 <section class="rendered-data">

 <details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>
--- a/layouts/_partials/spec-content.html
+++ b/layouts/_partials/spec-content.html
@ -0,0 +1,14 @@
+{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}}
+<div class="td-content">
+  <h1>{{ .Title }}</h1>
+  {{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ end }}
+
+  {{/*
+    Render an endpoints table of contents. This is the main difference
+    between our templates (which call the spec-content partial) and the default
+    Docsy template.
+  */}}
+  {{ partial "endpoints-toc.html" . }}
+
+  {{ .Content }}
+</div>
--- a/layouts/_shortcodes/cs-module.html
+++ b/layouts/_shortcodes/cs-module.html
@ -3,14 +3,39 @@
    This template is used to render a Client-Server API Module. Modules are defined
    alongside the `_index.md` for the CS API.

-    The `name` parameter is the file name without extension.
+    The following parameters are expected:
+
+    * `filename` the name of the module file to render, without extension (i.e. `spaces`).
+    * `name` the display name of the module (i.e. `Spaces`).

 */}}

 {{ $name := .Params.name }}
+{{ $filename := .Params.filename }}

 {{ with .Site.GetPage "client-server-api/modules" }}
-    {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }}
+    {{ with .Resources.GetMatch (printf "%s%s" $filename ".md") }}
+        {{/* Preserve previous scratch values so nested modules don't leak */}}
+        {{ $prevPage := .Scratch.Get "endpoint_page" }}
+        {{ $prevModule := .Scratch.Get "endpoint_module" }}
+
+        {{/* Allow endpoints rendered in the module to accumulate on the parent page */}}
+        {{ .Scratch.Set "endpoint_page" $.Page }}
+        {{/* Name the module for grouping in the endpoints list */}}
+        {{ .Scratch.Set "endpoint_module" $name }}
+
 {{ .RenderShortcodes }}
+
+        {{/* Restore previous scratch values */}}
+        {{ if $prevPage }}
+          {{ .Scratch.Set "endpoint_page" $prevPage }}
+        {{ else }}
+          {{ .Scratch.Delete "endpoint_page" }}
+        {{ end }}
+        {{ if $prevModule }}
+          {{ .Scratch.Set "endpoint_module" $prevModule }}
+        {{ else }}
+          {{ .Scratch.Delete "endpoint_module" }}
+        {{ end }}
    {{ end }}
 {{ end }}
--- a/layouts/_shortcodes/http-api.html
+++ b/layouts/_shortcodes/http-api.html
@ -23,6 +23,20 @@
 {{ $api := .Params.api}}
 {{ $anchor_base := .Params.anchor_base}}

+{{/*
+  
+  Figure out which Page object to pass to the `openapi/render-api` partial.
+  Either our own, or one stored under `endpoint_page` in the Scratch, if one
+  exists.
+
+*/}}
+{{ $target_page := .Page }}
+{{ with .Page.Scratch.Get "endpoint_page" }}
+  {{ $target_page = . }}
+{{ end }}
+
+{{ $module_name := .Page.Scratch.Get "endpoint_module" }}
+
 {{ $api_data := index .Site.Data.api .Params.spec .Params.api }}
 {{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
 {{ $path := delimit (slice "api" $spec $api) "/" }}
@ -30,4 +44,4 @@
 {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
 {{ $api_data = partial "json-schema/resolve-allof" $api_data }}

-{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }}
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" $target_page "module" $module_name) }}
--- a/layouts/content.html
+++ b/layouts/content.html
@ -1,4 +0,0 @@
-<div class="td-content">
-	<h1>{{ .Title }}</h1>
-	{{ .Content }}
-</div>
--- a/layouts/docs/list.html
+++ b/layouts/docs/list.html
@ -1,13 +1,19 @@
 {{/*

-  A simplified version of the list.html partial in Docsy.
+  Override the `layouts/docs/list.html` template from Docsy. While this template
+  is equivalent to `single.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#list
+
+  We use this list template to render the Client-Server API spec page and each
+  of its modules.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.

 */}}

 {{ define "main" }}
-<div class="td-content">
-	<h1>{{ .Title }}</h1>
-        {{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
-	{{ .Content }}
-</div>
+  {{ partial "spec-content.html" . }}
 {{ end }}
--- a/layouts/docs/single.html
+++ b/layouts/docs/single.html
@ -0,0 +1,19 @@
+{{/*
+
+  Override the `layouts/docs/single.html` template from Docsy. While this template
+  is equivalent to `list.html`, it's necessary to override both templates to
+  avoid falling back to the default Docsy templates.
+
+  https://gohugo.io/templates/types/#single
+
+  We use this single template to render the all API spec pages *except* the
+  Client-Server API. The Client-Server API spec page contains modules, and thus
+  is handled separately, via the `layouts/docs/list.html` template.
+
+  The contents of the "main" block below are inserted into the `./baseof.html`
+  base template.
+
+*/}}
+{{ define "main" }}
+  {{ partial "spec-content.html" . }}
+{{ end }}
Author	SHA1	Message	Date
Kévin Commaille	abaf20a775	Merge `3c17aa3789` into `6b5ff04d00`	2025-12-18 18:44:36 +00:00
Richard van der Hoff	6b5ff04d00	Return `main` to unstable status Some checks are pending Spec / 🔎 Validate OpenAPI specifications (push) Waiting to run Details Spec / 🔎 Check Event schema examples (push) Waiting to run Details Spec / 🔎 Check OpenAPI definitions examples (push) Waiting to run Details Spec / 🔎 Check JSON Schemas inline examples (push) Waiting to run Details Spec / ⚙️ Calculate baseURL for later jobs (push) Waiting to run Details Spec / 🐍 Build OpenAPI definitions (push) Blocked by required conditions Details Spec / 📢 Run towncrier for changelog (push) Waiting to run Details Spec / 📖 Build the spec (push) Blocked by required conditions Details Spec / 🔎 Validate generated HTML (push) Blocked by required conditions Details Spec / 📖 Build the historical backup spec (push) Blocked by required conditions Details Spell Check / Spell Check with Typos (push) Waiting to run Details	2025-12-18 16:30:28 +00:00
Richard van der Hoff	ce5ae4d371	missing comma	2025-12-18 16:07:32 +00:00
Richard van der Hoff	27315feb17	Minor changelog edits	2025-12-18 15:57:59 +00:00
Richard van der Hoff	a1c930d0d1	Prepare v1.17 release	2025-12-18 15:53:35 +00:00
Andrew Morgan	9e959f3922	Add a list of endpoints to the top of each spec (#2262 ) Fixes #784 Add a collapsible list of endpoints to the top of the page for each distinct spec. We do this by storing endpoint metadata on $page and creating a new partial, endpoints-toc.html, which renders it.	2025-12-18 14:59:18 +00:00
Kévin Commaille	3c17aa3789	Add changelog Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>	2025-07-25 10:44:39 +02:00
Kévin Commaille	506bc1a164	Clarify that stripped state in /sync response must include `m.room.member` event of user And that event has the same format as in join rooms, with `event_id` and `origin_server_ts`. This has always been the case in homeserver implementations. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>	2025-07-25 09:56:33 +02:00
				`@ -1 +0,0 @@`
				`Fix JSON formatting in the "Server admin style permissions" examples.`
				`@ -1 +0,0 @@`
				`Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326).`
				`@ -1 +0,0 @@`
				`Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190).`
				`@ -1 +0,0 @@`
				`Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).`
				`@ -1 +0,0 @@`
				`Push rule IDs are globally unique within their kind.`
				`@ -1 +0,0 @@`
				Don't advertise `creator` field in description of room creation.
				`@ -1 +0,0 @@`
				`room_id` is required for peeking via `/_matrix/client/v3/events`.
				`@ -1 +0,0 @@`
				The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment.
				`@ -1 +0,0 @@`
				`Add note to each endpoint that uses capability negotiation.`