summary refs log tree commit diff
diff options
context:
space:
mode:
authorMichael Weimann <michaelw@element.io>2023-11-17 14:38:25 +0100
committerGitHub <noreply@github.com>2023-11-17 13:38:25 +0000
commit518e4de758147785f797057b507d2f69a9118c9e (patch)
tree6f5abea962875f50c9629becf5dd2b6c173478c1
parentReduce task concurrency (#16656) (diff)
downloadsynapse-518e4de758147785f797057b507d2f69a9118c9e.tar.xz
Update admin user API return types in docs. (#16654)
-rw-r--r--changelog.d/16654.doc1
-rw-r--r--docs/admin_api/user_admin_api.md19
2 files changed, 16 insertions, 4 deletions
diff --git a/changelog.d/16654.doc b/changelog.d/16654.doc
new file mode 100644
index 0000000000..61019e0367
--- /dev/null
+++ b/changelog.d/16654.doc
@@ -0,0 +1 @@
+Provide an example for a common encrypted media response from the admin user media API and mention possible null values.
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 66089c634b..e8e492d095 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -618,6 +618,16 @@ A response body like the following is returned:
       "quarantined_by": null,
       "safe_from_quarantine": false,
       "upload_name": "test2.png"
+    },
+    {
+      "created_ts": 300400,
+      "last_access_ts": 300700,
+      "media_id": "BzYNLRUgGHphBkdKGbzXwbjX",
+      "media_length": 1337,
+      "media_type": "application/octet-stream",
+      "quarantined_by": null,
+      "safe_from_quarantine": false,
+      "upload_name": null
     }
   ],
   "next_token": 3,
@@ -679,16 +689,17 @@ The following fields are returned in the JSON response body:
 - `media` - An array of objects, each containing information about a media.
   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.
+  - `last_access_ts` - integer or null - Timestamp when the content was last accessed in ms.
+     Null if there was no access, yet.
   - `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
-    for this media.
+  - `quarantined_by` - string or null - The user ID that initiated the quarantine request
+    for this media. Null if not quarantined.
   - `safe_from_quarantine` - bool - Status if this media is safe from quarantining.
-  - `upload_name` - string - The name the media was uploaded with.
+  - `upload_name` - string or null - The name the media was uploaded with. Null if not provided during upload.
 - `next_token`: integer - Indication for pagination. See above.
 - `total` - integer - Total number of media.