From 355e06eaa6f6d3405f25e6ced8f9b4ac0c89e0fe Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 4 Jan 2022 16:45:10 +0000
Subject: [PATCH] Clarification for `/event_auth` (#3583)

The description on this endpoint implied it returned the auth chain for the
full state of the room, which is incorrect.
---
 .../server_server/newsfragments/3583.clarification   |  1 +
 data/api/server-server/event_auth.yaml               | 12 ++++--------
 2 files changed, 5 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/3583.clarification

diff --git a/changelogs/server_server/newsfragments/3583.clarification b/changelogs/server_server/newsfragments/3583.clarification
new file mode 100644
index 00000000..1192d612
--- /dev/null
+++ b/changelogs/server_server/newsfragments/3583.clarification
@@ -0,0 +1 @@
+Clarify that `GET /_matrix/federation/v1/event_auth/{roomId}/{eventId}` does *not* return the auth chain for the full state of the room.
diff --git a/data/api/server-server/event_auth.yaml b/data/api/server-server/event_auth.yaml
index 26cdd95a..8a2d47bf 100644
--- a/data/api/server-server/event_auth.yaml
+++ b/data/api/server-server/event_auth.yaml
@@ -57,17 +57,13 @@ paths:
               auth_chain:
                 type: array
                 description: |-
-                  The full set of authorization events that make up the state of
-                  the room, and their authorization events, recursively. Note that
-                  events have a different format depending on the room version -
-                  check the [room version specification](/rooms) for precise event formats.
+                  The [PDUs](/server-server-api/#pdus) forming the auth chain
+                  of the given event. The event format varies depending on the
+                  room version - check the [room version specification](/rooms)
+                  for precise event formats.
                 items:
                   type: object
                   title: PDU
-                  description: |-
-                    The [PDUs](/server-server-api/#pdus) contained in the auth chain. The event format
-                    varies depending on the room version - check the [room version specification](/rooms)
-                    for precise event formats.
                   properties: []
                   example:
                     $ref: "examples/minimal_pdu.json"