diff --git a/docs/api.md b/docs/api.md
index da27d3e07..5282cc76f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -288,10 +288,22 @@ with an optional `set_permissions` parameter which is of the form:
 }
 ```
 
+!!! note
+
+    Arrays should contain user or group ID numbers.
+
 If this parameter is supplied the object's permissions will be overwritten,
 assuming the authenticated user has permission to do so (the user must be
 the object owner or a superuser).
 
+### Retrieving full permissions
+
+By default, the API will return a truncated version of object-level
+permissions, returning `user_can_change` indicating whether the current user
+has edit permissions. You can pass the parameter `full_perms=true` to API
+calls to view the full permissions of objects in a format that mirrors the
+`set_permissions` parameter above.
+
 ## API Versioning
 
 The REST API is versioned since Paperless-ngx 1.3.0.