From 65ef21b1c7b4297d6a7b2888de4cbfe198ac0324 Mon Sep 17 00:00:00 2001
From: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com>
Date: Fri, 4 Feb 2022 15:39:14 +0100
Subject: [PATCH] Clarify that users' media are also preview images (#11862)

---
 changelog.d/11862.doc             | 1 +
 docs/admin_api/media_admin_api.md | 3 +++
 docs/admin_api/user_admin_api.md  | 9 ++++++++-
 3 files changed, 12 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/11862.doc

diff --git a/changelog.d/11862.doc b/changelog.d/11862.doc
new file mode 100644
index 0000000000..98e32e7325
--- /dev/null
+++ b/changelog.d/11862.doc
@@ -0,0 +1 @@
+Document images returned by the User List Media Admin API can include those generated by URL previews.
diff --git a/docs/admin_api/media_admin_api.md b/docs/admin_api/media_admin_api.md
index a8cdf19727..96b3668f2a 100644
--- a/docs/admin_api/media_admin_api.md
+++ b/docs/admin_api/media_admin_api.md
@@ -2,6 +2,9 @@
 
 These APIs allow extracting media information from the homeserver.
 
+Details about the format of the `media_id` and storage of the media in the file system
+are documented under [media repository](../media_repository.md).
+
 To use it, you will need to authenticate by providing an `access_token`
 for a server admin: see [Admin API](../usage/administration/admin_api).
 
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 995782c6bc..1bbe237080 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -539,6 +539,11 @@ The following fields are returned in the JSON response body:
 
 ### List media uploaded by a user
 Gets a list of all local media that a specific `user_id` has created.
+These are media that the user has uploaded themselves
+([local media](../media_repository.md#local-media)), as well as
+[URL preview images](../media_repository.md#url-previews) requested by the user if the
+[feature is enabled](../development/url_previews.md).
+
 By default, the response is ordered by descending creation date and ascending media ID.
 The newest media is on top. You can change the order with parameters
 `order_by` and `dir`.
@@ -635,7 +640,9 @@ The following fields are returned in the JSON response body:
   Media objects contain the following fields:
   - `created_ts` - integer - Timestamp when the content was uploaded in ms.
   - `last_access_ts` - integer - Timestamp when the content was last accessed in ms.
-  - `media_id` - string - The id used to refer to the media.
+  - `media_id` - string - The id used to refer to the media. Details about the format
+    are documented under
+    [media repository](../media_repository.md).
   - `media_length` - integer - Length of the media in bytes.
   - `media_type` - string - The MIME-type of the media.
   - `quarantined_by` - string - The user ID that initiated the quarantine request