diff --git a/app/Http/Controllers/Api/ContentPermissionsController.php b/app/Http/Controllers/Api/ContentPermissionsController.php
index 1db90f97a..ef17af8ad 100644
--- a/app/Http/Controllers/Api/ContentPermissionsController.php
+++ b/app/Http/Controllers/Api/ContentPermissionsController.php
@@ -54,13 +54,13 @@ class ContentPermissionsController extends ApiController
     }
 
     /**
-     * Update the configured content-level permissions for the item of the given type and ID.
+     * Update the configured content-level permission overrides for the item of the given type and ID.
      * 'contentType' should be one of: page, book, chapter, bookshelf.
      * 'contentId' should be the relevant ID of that item type you'd like to handle permissions for.
      * Providing an empty `role_permissions` array will remove any existing configured role permissions,
      * so you may want to fetch existing permissions beforehand if just adding/removing a single item.
      * You should completely omit the `owner_id`, `role_permissions` and/or the `fallback_permissions` properties
-     * if you don't wish to update details within those categories.
+     * from your request data if you don't wish to update details within those categories.
      */
     public function update(Request $request, string $contentType, string $contentId)
     {
diff --git a/dev/api/requests/content-permissions-update.json b/dev/api/requests/content-permissions-update.json
new file mode 100644
index 000000000..124bb8bff
--- /dev/null
+++ b/dev/api/requests/content-permissions-update.json
@@ -0,0 +1,26 @@
+{
+  "owner_id": 1,
+  "role_permissions": [
+    {
+      "role_id": 2,
+      "view": true,
+      "create": true,
+      "update": true,
+      "delete": false
+    },
+    {
+      "role_id": 3,
+      "view": false,
+      "create": false,
+      "update": false,
+      "delete": false
+    }
+  ],
+  "fallback_permissions": {
+    "inheriting": false,
+    "view": true,
+    "create": true,
+    "update": false,
+    "delete": false
+  }
+}
\ No newline at end of file
diff --git a/dev/api/responses/content-permissions-read.json b/dev/api/responses/content-permissions-read.json
new file mode 100644
index 000000000..591fc5c86
--- /dev/null
+++ b/dev/api/responses/content-permissions-read.json
@@ -0,0 +1,38 @@
+{
+  "owner": {
+    "id": 1,
+    "name": "Admin",
+    "slug": "admin"
+  },
+  "role_permissions": [
+    {
+      "role_id": 2,
+      "view": true,
+      "create": false,
+      "update": true,
+      "delete": false,
+      "role": {
+        "id": 2,
+        "display_name": "Editor"
+      }
+    },
+    {
+      "role_id": 10,
+      "view": true,
+      "create": true,
+      "update": false,
+      "delete": false,
+      "role": {
+        "id": 10,
+        "display_name": "Wizards of the west"
+      }
+    }
+  ],
+  "fallback_permissions": {
+    "inheriting": false,
+    "view": true,
+    "create": false,
+    "update": false,
+    "delete": false
+  }
+}
\ No newline at end of file
diff --git a/dev/api/responses/content-permissions-update.json b/dev/api/responses/content-permissions-update.json
new file mode 100644
index 000000000..67fa40bf0
--- /dev/null
+++ b/dev/api/responses/content-permissions-update.json
@@ -0,0 +1,38 @@
+{
+  "owner": {
+    "id": 1,
+    "name": "Admin",
+    "slug": "admin"
+  },
+  "role_permissions": [
+    {
+      "role_id": 2,
+      "view": true,
+      "create": true,
+      "update": true,
+      "delete": false,
+      "role": {
+        "id": 2,
+        "display_name": "Editor"
+      }
+    },
+    {
+      "role_id": 3,
+      "view": false,
+      "create": false,
+      "update": false,
+      "delete": false,
+      "role": {
+        "id": 3,
+        "display_name": "Viewer"
+      }
+    }
+  ],
+  "fallback_permissions": {
+    "inheriting": false,
+    "view": true,
+    "create": true,
+    "update": false,
+    "delete": false
+  }
+}
\ No newline at end of file