From 8a6d9a8d4550c3b0f6232ef5a2a5bfa51fbc5534 Mon Sep 17 00:00:00 2001
From: Andrew Ferrazzutti <andrewf@element.io>
Date: Tue, 17 Mar 2026 10:36:07 -0400
Subject: [PATCH] Admin API docs: use consistent path param syntax (#19307)

Always use `/<param>` instead of sometimes using `/$param`

### Pull Request Checklist

<!-- Please read
https://element-hq.github.io/synapse/latest/development/contributing_guide.html
before submitting your pull request -->

* [x] Pull request is based on the develop branch
* [x] Pull request includes a [changelog
file](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#changelog).
The entry should:
- Be a short description of your change which makes sense to users.
"Fixed a bug that prevented receiving messages from other servers."
instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
  - Use markdown where necessary, mostly for `code blocks`.
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by
@github_username." or "Contributed by [Your Name]." to the end of the
entry.
* [x] [Code
style](https://element-hq.github.io/synapse/latest/code_style.html) is
correct (run the
[linters](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-linters))
---
 changelog.d/19307.doc            |  1 +
 docs/admin_api/user_admin_api.md | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)
 create mode 100644 changelog.d/19307.doc

diff --git a/changelog.d/19307.doc b/changelog.d/19307.doc
new file mode 100644
index 0000000000..a27e97f3d0
--- /dev/null
+++ b/changelog.d/19307.doc
@@ -0,0 +1 @@
+In the Admin API documentation, always express path parameters as `/<param>` instead of as `/$param`.
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 72e0e8d91a..14f86fa976 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -600,7 +600,7 @@ Fetches the number of invites sent by the provided user ID across all rooms
 after the given timestamp.
 
 ```
-GET /_synapse/admin/v1/users/$user_id/sent_invite_count
+GET /_synapse/admin/v1/users/<user_id>/sent_invite_count
 ```
 
 **Parameters**
@@ -634,7 +634,7 @@ Fetches the number of rooms that the user joined after the given timestamp, even
 if they have subsequently left/been banned from those rooms.
 
 ```
-GET /_synapse/admin/v1/users/$<user_id/cumulative_joined_room_count
+GET /_synapse/admin/v1/users/<user_id>/cumulative_joined_room_count
 ```
 
 **Parameters**
@@ -1439,7 +1439,7 @@ The request and response format is the same as the
 The API is:
 
 ```
-GET /_synapse/admin/v1/auth_providers/$provider/users/$external_id
+GET /_synapse/admin/v1/auth_providers/<provider>/users/<external_id>
 ```
 
 When a user matched the given ID for the given provider, an HTTP code `200` with a response body like the following is returned:
@@ -1478,7 +1478,7 @@ _Added in Synapse 1.68.0._
 The API is:
 
 ```
-GET /_synapse/admin/v1/threepid/$medium/users/$address
+GET /_synapse/admin/v1/threepid/<medium>/users/<address>
 ```
 
 When a user matched the given address for the given medium, an HTTP code `200` with a response body like the following is returned:
@@ -1522,7 +1522,7 @@ is provided to override the default and allow the admin to issue the redactions
 
 The API is 
 ```
-POST /_synapse/admin/v1/user/$user_id/redact
+POST /_synapse/admin/v1/user/<user_id>/redact
 
 {
   "rooms": ["!roomid1", "!roomid2"]
@@ -1571,7 +1571,7 @@ or until Synapse is restarted (whichever happens first).
 The API is:
 
 ```
-GET /_synapse/admin/v1/user/redact_status/$redact_id
+GET /_synapse/admin/v1/user/redact_status/<redact_id>
 ```
 
 A response body like the following is returned: