diff --git a/changelog.d/4-docs/hook-fedcalls-into-api-docs b/changelog.d/4-docs/hook-fedcalls-into-api-docs
new file mode 100644
index 0000000000..2a6d02a8a3
--- /dev/null
+++ b/changelog.d/4-docs/hook-fedcalls-into-api-docs
@@ -0,0 +1 @@
+Hook federated API call documentation into docs.wire.com (manually).
diff --git a/docs/src/configuration-options.md b/docs/src/configuration-options.md
index 647ac5f0ee..1eeee72383 100644
--- a/docs/src/configuration-options.md
+++ b/docs/src/configuration-options.md
@@ -431,11 +431,11 @@ helm upgrade --install --namespace metallb-system metallb wire/metallb \
 Install `nginx-ingress-[controller,services]`:
 
 ::
-: helm upgrade --install --namespace demo demo-nginx-ingress-controller wire/nginx-ingress-controller 
+: helm upgrade --install --namespace demo demo-nginx-ingress-controller wire/nginx-ingress-controller
 
   : --wait
 
-  helm upgrade --install --namespace demo demo-nginx-ingress-services wire/nginx-ingress-services 
+  helm upgrade --install --namespace demo demo-nginx-ingress-services wire/nginx-ingress-services
 
   : -f values/nginx-ingress-services/demo-values.yaml -f values/nginx-ingress-services/demo-secrets.yaml --wait
 
@@ -633,7 +633,7 @@ account-pages:
 
 ## Configuring authentication cookie throttling
 
-Authentication cookies and the related throttling mechanism is described in the *Client API documentation*:
+Authentication cookies and the related throttling mechanism is described in the *API documentation*:
 {ref}`login-cookies`
 
 The maximum number of cookies per account and type is defined by the brig option
diff --git a/docs/src/index.md b/docs/src/index.md
index 135a0aa03f..da0c17e170 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -30,7 +30,7 @@ Connecting Wire Clients <how-to/associate/index>
 Optional Configuration <configuration-options>
 Understanding wire-server components <understand/index>
 Single-Sign-On and user provisioning <how-to/single-sign-on/index.rst>
-Client API documentation <understand/api-client-perspective/index>
+API documentation <understand/api-client-perspective/index>
 Security responses <security-responses/index>
 Notes for developers <developer/index>
 ```
diff --git a/docs/src/understand/api-client-perspective/index.md b/docs/src/understand/api-client-perspective/index.md
index 8bf19e4290..e86c0de1f2 100644
--- a/docs/src/understand/api-client-perspective/index.md
+++ b/docs/src/understand/api-client-perspective/index.md
@@ -2,10 +2,6 @@
 
 The following documentation provides information for, and takes the perspective of a Wire client developer. (wire-desktop, wire-android and wire-ios are examples of Wire Clients). This means only publicly accessible endpoints are mentioned.
 
-```{warning}
-This section of the documentation is very incomplete at the time of writing (summer 2020) - more pages on the client API will follow in the future.
-```
-
 ```{toctree}
 :glob: true
 :maxdepth: 2
diff --git a/docs/src/understand/api-client-perspective/swagger.md b/docs/src/understand/api-client-perspective/swagger.md
index 057d5beb2a..5722c95aed 100644
--- a/docs/src/understand/api-client-perspective/swagger.md
+++ b/docs/src/understand/api-client-perspective/swagger.md
@@ -3,24 +3,20 @@
 Our staging system provides swagger documentation of our public rest
 API.
 
-We are currently (as of 2021-09-29) migrating our documentation into a
-new system that is automatically checked for correctness. The old
-documentation still has some endpoints, but the new one is getting more and more complete. We will completely replace the old one eventually.
+The swagger docs are correct by construction (compiled from the server
+code), and the are complete up to bots/services and event notification
+payloads (as of 2023-01-16).
 
 Please check the new docs first, and if you can't find what you're
 looking for, double-check the old.
 
-## New docs
-
-These docs show swagger 2.0:
+## New docs (swagger 2.0)
 
 [new staging swagger page](https://staging-nginz-https.zinfra.io/api/swagger-ui/)
 
-## Old docs
-
-Some endpoints are only shown using swagger 1.2.
+## Old docs (swagger 1.2)
 
-At the time of writing, both swagger version 1.2 and version 2.0 are in use. If you are an employee of Wire, you can log in here and try out requests in the browser; if not, you can make use of the "List Operations" button on both 1.2 and 2.0 pages to see the possible API requests.
+If you are an employee of Wire, you can log in here and try out requests in the browser; if not, you can make use of the "List Operations" button on both 1.2 and 2.0 pages to see the possible API requests.
 
 Browse to our [old staging swagger page](https://staging-nginz-https.zinfra.io/swagger-ui/) to see rendered swagger documentation for the remaining endpoints.
 
diff --git a/docs/src/understand/federation/fedcalls.md b/docs/src/understand/federation/fedcalls.md
new file mode 100644
index 0000000000..80fdb3c03e
--- /dev/null
+++ b/docs/src/understand/federation/fedcalls.md
@@ -0,0 +1,18 @@
+# Federated API calls by client API end-point (generated)
+
+**Updated manually using using [the fedcalls tool](https://github.com/wireapp/wire-server/blob/8760b4978ccb039b229d458b7a08136a05e12ff9/tools/fedcalls/README.md); last change: 2023-01-16.**
+
+This is most likely only interesting for backend developers.
+
+This graph and csv file describe which public (client) API end-points trigger calls to which end-points at backends federating with the one that is called.  The data is correct by construction (see [the fedcalls tool](https://github.com/wireapp/wire-server/blob/8760b4978ccb039b229d458b7a08136a05e12ff9/tools/fedcalls/README.md) for more details).
+
+The target can only be understood in the context of the [backend code base](https://github.com/wireapp/wire-server/).  It is described by component (sub-directory in `/services`) and end-point name (use grep to find it).
+
+links:
+
+- [dot](img/wire-fedcalls.dot)
+- [png](img/wire-fedcalls.png)
+- [csv](img/wire-fedcalls.csv)
+
+```{image} img/wire-fedcalls.png
+```
diff --git a/docs/src/understand/federation/img/wire-fedcalls.csv b/docs/src/understand/federation/img/wire-fedcalls.csv
new file mode 100644
index 0000000000..bfc571a6d8
--- /dev/null
+++ b/docs/src/understand/federation/img/wire-fedcalls.csv
@@ -0,0 +1,122 @@
+source method,source path,target component,target name
+get,/users/{uid_domain}/{uid},brig,get-users-by-ids
+post,/list-users,brig,get-users-by-ids
+put,/self,brig,on-user-deleted-connections
+delete,/self,brig,on-user-deleted-connections
+delete,/self/phone,brig,on-user-deleted-connections
+delete,/self/email,brig,on-user-deleted-connections
+put,/self/locale,brig,on-user-deleted-connections
+put,/self/handle,brig,on-user-deleted-connections
+post,/register,brig,on-user-deleted-connections
+post,/delete,brig,on-user-deleted-connections
+get,/activate,brig,on-user-deleted-connections
+post,/activate,brig,on-user-deleted-connections
+get,/users/{uid_domain}/{uid}/clients,brig,get-user-clients
+get,/users/{uid_domain}/{uid}/clients/{client},brig,get-user-clients
+post,/users/list-clients,brig,get-user-clients
+get,/users/{uid_domain}/{uid}/prekeys/{client},brig,claim-prekey
+get,/users/{uid_domain}/{uid}/prekeys,brig,claim-prekey-bundle
+post,/users/list-prekeys,brig,claim-multi-prekey-bundle
+post,/clients,brig,on-user-deleted-connections
+put,/connections/{uid_domain}/{uid},brig,send-connection-action
+post,/connections/{uid_domain}/{uid},brig,send-connection-action
+get,/search/contacts,brig,get-users-by-ids
+get,/search/contacts,brig,search-users
+post,/mls/key-packages/claim/{user_domain}/{user},brig,claim-key-packages
+post,/access,brig,on-user-deleted-connections
+post,/login,brig,on-user-deleted-connections
+get,/assets/{key_domain}/{key},cargohold,get-asset
+get,/assets/{key_domain}/{key},cargohold,stream-asset
+put,/conversations/{cnv},galley,on-conversation-updated
+put,/conversations/{cnv},galley,on-mls-message-sent
+put,/conversations/{cnv},galley,on-new-remote-conversation
+get,/conversations/{cnv_domain}/{cnv},galley,get-conversations
+get,/conversations/{cnv_domain}/{cnv}/groupinfo,galley,query-group-info
+post,/conversations/list,galley,get-conversations
+post,/conversations/join,galley,on-conversation-updated
+post,/conversations/join,galley,on-new-remote-conversation
+post,/conversations,galley,on-conversation-created
+post,/conversations/one2one,galley,on-conversation-created
+post,/conversations/{cnv_domain}/{cnv}/members,galley,on-conversation-updated
+post,/conversations/{cnv_domain}/{cnv}/members,galley,on-mls-message-sent
+post,/conversations/{cnv_domain}/{cnv}/members,galley,on-new-remote-conversation
+post,/conversations/{cnv}/join,galley,on-conversation-updated
+post,/conversations/{cnv}/join,galley,on-new-remote-conversation
+post,/conversations/{cnv_domain}/{cnv}/typing,galley,on-typing-indicator-updated
+put,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-conversation-updated
+put,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-mls-message-sent
+put,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-new-remote-conversation
+delete,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,leave-conversation
+delete,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-conversation-updated
+delete,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-mls-message-sent
+delete,/conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr},galley,on-new-remote-conversation
+put,/conversations/{cnv}/members/{usr},galley,on-conversation-updated
+put,/conversations/{cnv}/members/{usr},galley,on-mls-message-sent
+put,/conversations/{cnv}/members/{usr},galley,on-new-remote-conversation
+put,/conversations/{cnv}/name,galley,on-conversation-updated
+put,/conversations/{cnv}/name,galley,on-mls-message-sent
+put,/conversations/{cnv}/name,galley,on-new-remote-conversation
+put,/conversations/{cnv_domain}/{cnv}/name,galley,on-conversation-updated
+put,/conversations/{cnv_domain}/{cnv}/name,galley,on-mls-message-sent
+put,/conversations/{cnv_domain}/{cnv}/name,galley,on-new-remote-conversation
+put,/conversations/{cnv}/message-timer,galley,on-conversation-updated
+put,/conversations/{cnv}/message-timer,galley,on-mls-message-sent
+put,/conversations/{cnv}/message-timer,galley,on-new-remote-conversation
+put,/conversations/{cnv_domain}/{cnv}/message-timer,galley,on-conversation-updated
+put,/conversations/{cnv_domain}/{cnv}/message-timer,galley,on-mls-message-sent
+put,/conversations/{cnv_domain}/{cnv}/message-timer,galley,on-new-remote-conversation
+put,/conversations/{cnv}/receipt-mode,galley,on-conversation-updated
+put,/conversations/{cnv}/receipt-mode,galley,on-mls-message-sent
+put,/conversations/{cnv}/receipt-mode,galley,on-new-remote-conversation
+put,/conversations/{cnv}/receipt-mode,galley,update-conversation
+put,/conversations/{cnv_domain}/{cnv}/receipt-mode,galley,on-conversation-updated
+put,/conversations/{cnv_domain}/{cnv}/receipt-mode,galley,on-mls-message-sent
+put,/conversations/{cnv_domain}/{cnv}/receipt-mode,galley,on-new-remote-conversation
+put,/conversations/{cnv_domain}/{cnv}/receipt-mode,galley,update-conversation
+put,/conversations/{cnv_domain}/{cnv}/access,galley,on-conversation-updated
+put,/conversations/{cnv_domain}/{cnv}/access,galley,on-mls-message-sent
+put,/conversations/{cnv_domain}/{cnv}/access,galley,on-new-remote-conversation
+delete,/teams/{tid}/conversations/{cid},galley,on-conversation-updated
+delete,/teams/{tid}/conversations/{cid},galley,on-mls-message-sent
+delete,/teams/{tid}/conversations/{cid},galley,on-new-remote-conversation
+post,/conversations/{cnv}/otr/messages,galley,on-message-sent
+post,/conversations/{cnv}/otr/messages,brig,get-user-clients
+post,/conversations/{cnv_domain}/{cnv}/proteus/messages,brig,get-user-clients
+post,/conversations/{cnv_domain}/{cnv}/proteus/messages,galley,on-message-sent
+post,/conversations/{cnv_domain}/{cnv}/proteus/messages,galley,send-message
+post,/bot/messages,galley,on-message-sent
+post,/bot/messages,brig,get-user-clients
+put,/teams/{tid}/features/legalhold,galley,on-conversation-updated
+put,/teams/{tid}/features/legalhold,galley,on-mls-message-sent
+put,/teams/{tid}/features/legalhold,galley,on-new-remote-conversation
+post,/mls/welcome,galley,mls-welcome
+post,/mls/messages,galley,on-mls-message-sent
+post,/mls/messages,galley,send-mls-message
+post,/mls/messages,galley,on-conversation-updated
+post,/mls/messages,galley,on-new-remote-conversation
+post,/mls/messages,brig,get-mls-clients
+post,/mls/commit-bundles,galley,on-mls-message-sent
+post,/mls/commit-bundles,galley,mls-welcome
+post,/mls/commit-bundles,galley,send-mls-commit-bundle
+post,/mls/commit-bundles,galley,on-conversation-updated
+post,/mls/commit-bundles,galley,on-new-remote-conversation
+post,/mls/commit-bundles,brig,get-mls-clients
+delete,/teams/{tid}/legalhold/settings,galley,on-conversation-updated
+delete,/teams/{tid}/legalhold/settings,galley,on-mls-message-sent
+delete,/teams/{tid}/legalhold/settings,galley,on-new-remote-conversation
+post,/teams/{tid}/legalhold/{uid},galley,on-conversation-updated
+post,/teams/{tid}/legalhold/{uid},galley,on-mls-message-sent
+post,/teams/{tid}/legalhold/{uid},galley,on-new-remote-conversation
+delete,/teams/{tid}/legalhold/{uid},galley,on-conversation-updated
+delete,/teams/{tid}/legalhold/{uid},galley,on-mls-message-sent
+delete,/teams/{tid}/legalhold/{uid},galley,on-new-remote-conversation
+post,/teams/{tid}/legalhold/consent,galley,on-conversation-updated
+post,/teams/{tid}/legalhold/consent,galley,on-mls-message-sent
+post,/teams/{tid}/legalhold/consent,galley,on-new-remote-conversation
+put,/teams/{tid}/legalhold/{uid}/approve,galley,on-conversation-updated
+put,/teams/{tid}/legalhold/{uid}/approve,galley,on-mls-message-sent
+put,/teams/{tid}/legalhold/{uid}/approve,galley,on-new-remote-conversation
+post,/i/users,brig,on-user-deleted-connections
+post,/i/users/spar,brig,on-user-deleted-connections
+post,/i/legalhold-login,brig,on-user-deleted-connections
+post,/i/sso-login,brig,on-user-deleted-connections
\ No newline at end of file
diff --git a/docs/src/understand/federation/img/wire-fedcalls.dot b/docs/src/understand/federation/img/wire-fedcalls.dot
new file mode 100644
index 0000000000..77648a9d95
--- /dev/null
+++ b/docs/src/understand/federation/img/wire-fedcalls.dot
@@ -0,0 +1,219 @@
+strict digraph {
+  graph [rankdir=LR]
+  node [shape=rectangle]
+  edge [style=dashed]
+  subgraph {
+    "37: delete /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w
+    "3: delete /self":w
+    "5: delete /self/email":w
+    "4: delete /self/phone":w
+    "46: delete /teams/{tid}/conversations/{cid}":w
+    "54: delete /teams/{tid}/legalhold/settings":w
+    "56: delete /teams/{tid}/legalhold/{uid}":w
+    "10: get /activate":w
+    "25: get /assets/{key_domain}/{key}":w
+    "27: get /conversations/{cnv_domain}/{cnv}":w
+    "28: get /conversations/{cnv_domain}/{cnv}/groupinfo":w
+    "21: get /search/contacts":w
+    "0: get /users/{uid_domain}/{uid}":w
+    "12: get /users/{uid_domain}/{uid}/clients":w
+    "13: get /users/{uid_domain}/{uid}/clients/{client}":w
+    "16: get /users/{uid_domain}/{uid}/prekeys":w
+    "15: get /users/{uid_domain}/{uid}/prekeys/{client}":w
+    "23: post /access":w
+    "11: post /activate":w
+    "49: post /bot/messages":w
+    "18: post /clients":w
+    "20: post /connections/{uid_domain}/{uid}":w
+    "31: post /conversations":w
+    "30: post /conversations/join":w
+    "29: post /conversations/list":w
+    "32: post /conversations/one2one":w
+    "33: post /conversations/{cnv_domain}/{cnv}/members":w
+    "48: post /conversations/{cnv_domain}/{cnv}/proteus/messages":w
+    "35: post /conversations/{cnv_domain}/{cnv}/typing":w
+    "34: post /conversations/{cnv}/join":w
+    "47: post /conversations/{cnv}/otr/messages":w
+    "9: post /delete":w
+    "61: post /i/legalhold-login":w
+    "62: post /i/sso-login":w
+    "59: post /i/users":w
+    "60: post /i/users/spar":w
+    "1: post /list-users":w
+    "24: post /login":w
+    "53: post /mls/commit-bundles":w
+    "22: post /mls/key-packages/claim/{user_domain}/{user}":w
+    "52: post /mls/messages":w
+    "51: post /mls/welcome":w
+    "8: post /register":w
+    "57: post /teams/{tid}/legalhold/consent":w
+    "55: post /teams/{tid}/legalhold/{uid}":w
+    "14: post /users/list-clients":w
+    "17: post /users/list-prekeys":w
+    "19: put /connections/{uid_domain}/{uid}":w
+    "45: put /conversations/{cnv_domain}/{cnv}/access":w
+    "36: put /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w
+    "42: put /conversations/{cnv_domain}/{cnv}/message-timer":w
+    "40: put /conversations/{cnv_domain}/{cnv}/name":w
+    "44: put /conversations/{cnv_domain}/{cnv}/receipt-mode":w
+    "26: put /conversations/{cnv}":w
+    "38: put /conversations/{cnv}/members/{usr}":w
+    "41: put /conversations/{cnv}/message-timer":w
+    "39: put /conversations/{cnv}/name":w
+    "43: put /conversations/{cnv}/receipt-mode":w
+    "2: put /self":w
+    "7: put /self/handle":w
+    "6: put /self/locale":w
+    "50: put /teams/{tid}/features/legalhold":w
+    "58: put /teams/{tid}/legalhold/{uid}/approve":w
+  }
+  subgraph {
+    "71: [brig]:claim-key-packages":e
+    "68: [brig]:claim-multi-prekey-bundle":e
+    "66: [brig]:claim-prekey":e
+    "67: [brig]:claim-prekey-bundle":e
+    "87: [brig]:get-mls-clients":e
+    "65: [brig]:get-user-clients":e
+    "63: [brig]:get-users-by-ids":e
+    "64: [brig]:on-user-deleted-connections":e
+    "70: [brig]:search-users":e
+    "69: [brig]:send-connection-action":e
+    "72: [cargohold]:get-asset":e
+    "73: [cargohold]:stream-asset":e
+    "77: [galley]:get-conversations":e
+    "81: [galley]:leave-conversation":e
+    "85: [galley]:mls-welcome":e
+    "79: [galley]:on-conversation-created":e
+    "74: [galley]:on-conversation-updated":e
+    "83: [galley]:on-message-sent":e
+    "75: [galley]:on-mls-message-sent":e
+    "76: [galley]:on-new-remote-conversation":e
+    "80: [galley]:on-typing-indicator-updated":e
+    "78: [galley]:query-group-info":e
+    "84: [galley]:send-message":e
+    "88: [galley]:send-mls-commit-bundle":e
+    "86: [galley]:send-mls-message":e
+    "82: [galley]:update-conversation":e
+  }
+  "0: get /users/{uid_domain}/{uid}":w -> "63: [brig]:get-users-by-ids":e
+  "1: post /list-users":w -> "63: [brig]:get-users-by-ids":e
+  "2: put /self":w -> "64: [brig]:on-user-deleted-connections":e
+  "3: delete /self":w -> "64: [brig]:on-user-deleted-connections":e
+  "4: delete /self/phone":w -> "64: [brig]:on-user-deleted-connections":e
+  "5: delete /self/email":w -> "64: [brig]:on-user-deleted-connections":e
+  "6: put /self/locale":w -> "64: [brig]:on-user-deleted-connections":e
+  "7: put /self/handle":w -> "64: [brig]:on-user-deleted-connections":e
+  "8: post /register":w -> "64: [brig]:on-user-deleted-connections":e
+  "9: post /delete":w -> "64: [brig]:on-user-deleted-connections":e
+  "10: get /activate":w -> "64: [brig]:on-user-deleted-connections":e
+  "11: post /activate":w -> "64: [brig]:on-user-deleted-connections":e
+  "12: get /users/{uid_domain}/{uid}/clients":w -> "65: [brig]:get-user-clients":e
+  "13: get /users/{uid_domain}/{uid}/clients/{client}":w -> "65: [brig]:get-user-clients":e
+  "14: post /users/list-clients":w -> "65: [brig]:get-user-clients":e
+  "15: get /users/{uid_domain}/{uid}/prekeys/{client}":w -> "66: [brig]:claim-prekey":e
+  "16: get /users/{uid_domain}/{uid}/prekeys":w -> "67: [brig]:claim-prekey-bundle":e
+  "17: post /users/list-prekeys":w -> "68: [brig]:claim-multi-prekey-bundle":e
+  "18: post /clients":w -> "64: [brig]:on-user-deleted-connections":e
+  "19: put /connections/{uid_domain}/{uid}":w -> "69: [brig]:send-connection-action":e
+  "20: post /connections/{uid_domain}/{uid}":w -> "69: [brig]:send-connection-action":e
+  "21: get /search/contacts":w -> "63: [brig]:get-users-by-ids":e
+  "21: get /search/contacts":w -> "70: [brig]:search-users":e
+  "22: post /mls/key-packages/claim/{user_domain}/{user}":w -> "71: [brig]:claim-key-packages":e
+  "23: post /access":w -> "64: [brig]:on-user-deleted-connections":e
+  "24: post /login":w -> "64: [brig]:on-user-deleted-connections":e
+  "25: get /assets/{key_domain}/{key}":w -> "72: [cargohold]:get-asset":e
+  "25: get /assets/{key_domain}/{key}":w -> "73: [cargohold]:stream-asset":e
+  "26: put /conversations/{cnv}":w -> "74: [galley]:on-conversation-updated":e
+  "26: put /conversations/{cnv}":w -> "75: [galley]:on-mls-message-sent":e
+  "26: put /conversations/{cnv}":w -> "76: [galley]:on-new-remote-conversation":e
+  "27: get /conversations/{cnv_domain}/{cnv}":w -> "77: [galley]:get-conversations":e
+  "28: get /conversations/{cnv_domain}/{cnv}/groupinfo":w -> "78: [galley]:query-group-info":e
+  "29: post /conversations/list":w -> "77: [galley]:get-conversations":e
+  "30: post /conversations/join":w -> "74: [galley]:on-conversation-updated":e
+  "30: post /conversations/join":w -> "76: [galley]:on-new-remote-conversation":e
+  "31: post /conversations":w -> "79: [galley]:on-conversation-created":e
+  "32: post /conversations/one2one":w -> "79: [galley]:on-conversation-created":e
+  "33: post /conversations/{cnv_domain}/{cnv}/members":w -> "74: [galley]:on-conversation-updated":e
+  "33: post /conversations/{cnv_domain}/{cnv}/members":w -> "75: [galley]:on-mls-message-sent":e
+  "33: post /conversations/{cnv_domain}/{cnv}/members":w -> "76: [galley]:on-new-remote-conversation":e
+  "34: post /conversations/{cnv}/join":w -> "74: [galley]:on-conversation-updated":e
+  "34: post /conversations/{cnv}/join":w -> "76: [galley]:on-new-remote-conversation":e
+  "35: post /conversations/{cnv_domain}/{cnv}/typing":w -> "80: [galley]:on-typing-indicator-updated":e
+  "36: put /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "74: [galley]:on-conversation-updated":e
+  "36: put /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "75: [galley]:on-mls-message-sent":e
+  "36: put /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "76: [galley]:on-new-remote-conversation":e
+  "37: delete /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "81: [galley]:leave-conversation":e
+  "37: delete /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "74: [galley]:on-conversation-updated":e
+  "37: delete /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "75: [galley]:on-mls-message-sent":e
+  "37: delete /conversations/{cnv_domain}/{cnv}/members/{usr_domain}/{usr}":w -> "76: [galley]:on-new-remote-conversation":e
+  "38: put /conversations/{cnv}/members/{usr}":w -> "74: [galley]:on-conversation-updated":e
+  "38: put /conversations/{cnv}/members/{usr}":w -> "75: [galley]:on-mls-message-sent":e
+  "38: put /conversations/{cnv}/members/{usr}":w -> "76: [galley]:on-new-remote-conversation":e
+  "39: put /conversations/{cnv}/name":w -> "74: [galley]:on-conversation-updated":e
+  "39: put /conversations/{cnv}/name":w -> "75: [galley]:on-mls-message-sent":e
+  "39: put /conversations/{cnv}/name":w -> "76: [galley]:on-new-remote-conversation":e
+  "40: put /conversations/{cnv_domain}/{cnv}/name":w -> "74: [galley]:on-conversation-updated":e
+  "40: put /conversations/{cnv_domain}/{cnv}/name":w -> "75: [galley]:on-mls-message-sent":e
+  "40: put /conversations/{cnv_domain}/{cnv}/name":w -> "76: [galley]:on-new-remote-conversation":e
+  "41: put /conversations/{cnv}/message-timer":w -> "74: [galley]:on-conversation-updated":e
+  "41: put /conversations/{cnv}/message-timer":w -> "75: [galley]:on-mls-message-sent":e
+  "41: put /conversations/{cnv}/message-timer":w -> "76: [galley]:on-new-remote-conversation":e
+  "42: put /conversations/{cnv_domain}/{cnv}/message-timer":w -> "74: [galley]:on-conversation-updated":e
+  "42: put /conversations/{cnv_domain}/{cnv}/message-timer":w -> "75: [galley]:on-mls-message-sent":e
+  "42: put /conversations/{cnv_domain}/{cnv}/message-timer":w -> "76: [galley]:on-new-remote-conversation":e
+  "43: put /conversations/{cnv}/receipt-mode":w -> "74: [galley]:on-conversation-updated":e
+  "43: put /conversations/{cnv}/receipt-mode":w -> "75: [galley]:on-mls-message-sent":e
+  "43: put /conversations/{cnv}/receipt-mode":w -> "76: [galley]:on-new-remote-conversation":e
+  "43: put /conversations/{cnv}/receipt-mode":w -> "82: [galley]:update-conversation":e
+  "44: put /conversations/{cnv_domain}/{cnv}/receipt-mode":w -> "74: [galley]:on-conversation-updated":e
+  "44: put /conversations/{cnv_domain}/{cnv}/receipt-mode":w -> "75: [galley]:on-mls-message-sent":e
+  "44: put /conversations/{cnv_domain}/{cnv}/receipt-mode":w -> "76: [galley]:on-new-remote-conversation":e
+  "44: put /conversations/{cnv_domain}/{cnv}/receipt-mode":w -> "82: [galley]:update-conversation":e
+  "45: put /conversations/{cnv_domain}/{cnv}/access":w -> "74: [galley]:on-conversation-updated":e
+  "45: put /conversations/{cnv_domain}/{cnv}/access":w -> "75: [galley]:on-mls-message-sent":e
+  "45: put /conversations/{cnv_domain}/{cnv}/access":w -> "76: [galley]:on-new-remote-conversation":e
+  "46: delete /teams/{tid}/conversations/{cid}":w -> "74: [galley]:on-conversation-updated":e
+  "46: delete /teams/{tid}/conversations/{cid}":w -> "75: [galley]:on-mls-message-sent":e
+  "46: delete /teams/{tid}/conversations/{cid}":w -> "76: [galley]:on-new-remote-conversation":e
+  "47: post /conversations/{cnv}/otr/messages":w -> "83: [galley]:on-message-sent":e
+  "47: post /conversations/{cnv}/otr/messages":w -> "65: [brig]:get-user-clients":e
+  "48: post /conversations/{cnv_domain}/{cnv}/proteus/messages":w -> "65: [brig]:get-user-clients":e
+  "48: post /conversations/{cnv_domain}/{cnv}/proteus/messages":w -> "83: [galley]:on-message-sent":e
+  "48: post /conversations/{cnv_domain}/{cnv}/proteus/messages":w -> "84: [galley]:send-message":e
+  "49: post /bot/messages":w -> "83: [galley]:on-message-sent":e
+  "49: post /bot/messages":w -> "65: [brig]:get-user-clients":e
+  "50: put /teams/{tid}/features/legalhold":w -> "74: [galley]:on-conversation-updated":e
+  "50: put /teams/{tid}/features/legalhold":w -> "75: [galley]:on-mls-message-sent":e
+  "50: put /teams/{tid}/features/legalhold":w -> "76: [galley]:on-new-remote-conversation":e
+  "51: post /mls/welcome":w -> "85: [galley]:mls-welcome":e
+  "52: post /mls/messages":w -> "75: [galley]:on-mls-message-sent":e
+  "52: post /mls/messages":w -> "86: [galley]:send-mls-message":e
+  "52: post /mls/messages":w -> "74: [galley]:on-conversation-updated":e
+  "52: post /mls/messages":w -> "76: [galley]:on-new-remote-conversation":e
+  "52: post /mls/messages":w -> "87: [brig]:get-mls-clients":e
+  "53: post /mls/commit-bundles":w -> "75: [galley]:on-mls-message-sent":e
+  "53: post /mls/commit-bundles":w -> "85: [galley]:mls-welcome":e
+  "53: post /mls/commit-bundles":w -> "88: [galley]:send-mls-commit-bundle":e
+  "53: post /mls/commit-bundles":w -> "74: [galley]:on-conversation-updated":e
+  "53: post /mls/commit-bundles":w -> "76: [galley]:on-new-remote-conversation":e
+  "53: post /mls/commit-bundles":w -> "87: [brig]:get-mls-clients":e
+  "54: delete /teams/{tid}/legalhold/settings":w -> "74: [galley]:on-conversation-updated":e
+  "54: delete /teams/{tid}/legalhold/settings":w -> "75: [galley]:on-mls-message-sent":e
+  "54: delete /teams/{tid}/legalhold/settings":w -> "76: [galley]:on-new-remote-conversation":e
+  "55: post /teams/{tid}/legalhold/{uid}":w -> "74: [galley]:on-conversation-updated":e
+  "55: post /teams/{tid}/legalhold/{uid}":w -> "75: [galley]:on-mls-message-sent":e
+  "55: post /teams/{tid}/legalhold/{uid}":w -> "76: [galley]:on-new-remote-conversation":e
+  "56: delete /teams/{tid}/legalhold/{uid}":w -> "74: [galley]:on-conversation-updated":e
+  "56: delete /teams/{tid}/legalhold/{uid}":w -> "75: [galley]:on-mls-message-sent":e
+  "56: delete /teams/{tid}/legalhold/{uid}":w -> "76: [galley]:on-new-remote-conversation":e
+  "57: post /teams/{tid}/legalhold/consent":w -> "74: [galley]:on-conversation-updated":e
+  "57: post /teams/{tid}/legalhold/consent":w -> "75: [galley]:on-mls-message-sent":e
+  "57: post /teams/{tid}/legalhold/consent":w -> "76: [galley]:on-new-remote-conversation":e
+  "58: put /teams/{tid}/legalhold/{uid}/approve":w -> "74: [galley]:on-conversation-updated":e
+  "58: put /teams/{tid}/legalhold/{uid}/approve":w -> "75: [galley]:on-mls-message-sent":e
+  "58: put /teams/{tid}/legalhold/{uid}/approve":w -> "76: [galley]:on-new-remote-conversation":e
+  "59: post /i/users":w -> "64: [brig]:on-user-deleted-connections":e
+  "60: post /i/users/spar":w -> "64: [brig]:on-user-deleted-connections":e
+  "61: post /i/legalhold-login":w -> "64: [brig]:on-user-deleted-connections":e
+  "62: post /i/sso-login":w -> "64: [brig]:on-user-deleted-connections":e
+}
\ No newline at end of file
diff --git a/docs/src/understand/federation/img/wire-fedcalls.png b/docs/src/understand/federation/img/wire-fedcalls.png
new file mode 100644
index 0000000000..35fb0ed9d2
Binary files /dev/null and b/docs/src/understand/federation/img/wire-fedcalls.png differ
diff --git a/tools/fedcalls/README.md b/tools/fedcalls/README.md
index e43f95e14a..bb62be4be4 100644
--- a/tools/fedcalls/README.md
+++ b/tools/fedcalls/README.md
@@ -15,10 +15,17 @@ dot -Tpng wire-fedcalls.dot > wire-fedcalls.png
 
 ### links
 
-- `./example.png`
+for users:
+
+- blog post explaining the technology: https://reasonablypolymorphic.com/blog/abusing-constraints/index.html
 - https://sketchviz.com/new
 - https://graphviz.org/doc/info/lang.html
-- `/libs/wire-api/src/Wire/API/MakesFederatedCall.hs`
+
+for developers:
+
+- `./example.png`
+- [MakesFederatedCall.hs (as of 2023-01-16)](https://github.com/wireapp/wire-server/blob/8760b4978ccb039b229d458b7a08136a05e12ff9/libs/wire-api/src/Wire/API/MakesFederatedCall.hs)
+- PRs: https://github.com/wireapp/wire-server/pull/2973, https://github.com/wireapp/wire-server/pull/2940, https://github.com/wireapp/wire-server/pull/2950, https://github.com/wireapp/wire-server/pull/2957
 
 ### swagger-ui