Docs: Update HTTP API docs for nested folders (#67412)

* Docs: Update HTTP API docs for nested folders

* Apply suggestions from code review

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

docs/sources/developers/http_api/folder.md

@@ -39,6 +39,10 @@ that you cannot use this API for retrieving information about the General folder
 
 Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the `limit` query parameter, the default is 1000. You can also pass the `page` query parameter for fetching folders from a page other than the first one.
 
+If nested folders are enabled, the operation expects an additional optional query parameter `parentUid` with the parent folder UID, and returns the immediate subfolders that the authenticated user has permission to view.
+If the parameter is not supplied, then the operation returns immediate subfolders under the root
+that the authenticated user has permission to view.
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
@@ -122,6 +126,11 @@ Content-Type: application/json
 | Action           | Scope       |
 | ---------------- | ----------- |
 | `folders:create` | n/a         |
+| `folders:write`  | `folders:*` |
+
+**Example Request**:
+
+```http
 POST /api/folders HTTP/1.1
 Accept: application/json
 Content-Type: application/json
@@ -162,7 +171,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 Updates an existing folder identified by uid.
 
 **Required permissions**
-| `folders:write` | `folders:*` |
+
 See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
 
 | Action          | Scope       |
@@ -188,6 +197,11 @@ Content-Type: application/json
 
 **Example Response**:
 
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
 
 If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
 
@@ -254,6 +268,11 @@ Content-Type: application/json
 Status Codes:
 
 - **200** – Deleted
+- **401** – Unauthorized
+- **400** – Bad Request
+- **403** – Access Denied
+- **404** – Folder not found
+
 ## Get folder by id
 
 `GET /api/folders/id/:id`
@@ -333,6 +352,8 @@ Status Codes:
 
 **Example Response**:
 
+```http
+HTTP/1.1 200
 Content-Type: application/json
 
 ```
@@ -379,3 +400,92 @@ Status Codes:
 - **401** – Unauthorized
 - **403** – Access Denied
 - **404** – Folder not found
+
+## Move folder
+
+`POST /api/folders/:uid/move`
+
+Moves the folder.
+
+This is relevant only if nested folders are enabled.
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
+
+If moving the folder under another folder:
+
+| Action          | Scope                                  |
+| --------------- | -------------------------------------- |
+| `folders:write` | `folders:uid:<destination folder UID>` |
+
+If moving the folder under root:
+| Action | Scope |
+| -------------- | ------------- |
+| `folders:create` | `folders:*` |
+
+JSON body schema:
+
+- **parentUid** – Optional [unique identifier]({{< relref "#identifier-id-vs-unique-identifier-uid" >}}) of the new parent folder. If this is empty, then the folder is moved under the root.
+
+**Example Request**:
+
+```http
+POST /api/folders/a5393ec3-5568-4e88-8809-b866968ae8a6/move HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
+}
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{
+	"id": 4,
+	"uid": "a5393ec3-5568-4e88-8809-b866968ae8a6",
+	"title": "just-testing",
+	"url": "/dashboards/f/a5393ec3-5568-4e88-8809-b866968ae8a6/just-testing",
+	"hasAcl": false,
+	"canSave": true,
+	"canEdit": true,
+	"canAdmin": true,
+	"canDelete": true,
+	"createdBy": "Anonymous",
+	"created": "2023-04-27T21:55:01.593741+03:00",
+	"updatedBy": "Anonymous",
+	"updated": "2023-04-27T21:55:15.747444+03:00",
+	"parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
+	"parents": [
+		{
+			"id": 2,
+			"uid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
+			"title": "f0",
+			"url": "",
+			"hasAcl": false,
+			"canSave": true,
+			"canEdit": true,
+			"canAdmin": true,
+			"canDelete": true,
+			"createdBy": "Anonymous",
+			"created": "2023-04-27T21:53:46.070672+03:00",
+			"updatedBy": "Anonymous",
+			"updated": "2023-04-27T21:53:46.070673+03:00"
+		}
+	]
+}
+```
+
+Status Codes:
+
+- **200** – Moved
+- **400** – Errors (invalid JSON, missing or invalid fields, and so on)
+- **401** – Unauthorized
+- **403** – Access denied
+- **404** – Not found