Document file and folder deletion endpoints

Author: johanohly

source/includes/_files.md

@@ -336,3 +336,142 @@ Also, folders cannot be moved into themselves.
 |-----------|---------|--------------------------------------------------------|
 | `status`  | boolean | True if the request was successful.                    |
 | `message` | string  | Success message or error message if `status` is false. |
+
+## Delete File(s)
+
+```shell
+curl https://api.simplyprint.io/{id}/files/DeleteFile?file=abc123,def456 \
+  -H 'accept: application/json' \
+  -H 'X-API-KEY: {API_KEY}'
+```
+
+> Success response
+
+```json
+{
+  "status": true,
+  "message": null,
+  "deleted": 2
+}
+```
+
+> Partial failure response (some files deleted, some failed)
+
+```json
+{
+  "status": false,
+  "message": "One or more files failed to be deleted",
+  "errors": [
+    "File abc123 doesn't exist or doesn't belong to you"
+  ],
+  "deleted": 1
+}
+```
+
+> Failure response: no file IDs specified
+
+```json
+{
+  "status": false,
+  "message": "No file ID(s) specified"
+}
+```
+
+> Failure response: no matching files found
+
+```json
+{
+  "status": false,
+  "message": "No file(s) with ID(s) exist"
+}
+```
+
+This endpoint deletes one or more files. Each file ID must belong to the requesting user and be modifiable; if any file
+cannot be deleted (e.g., due to missing permission or nonexistence), the call fails with error details.
+
+### Request
+
+`GET /{id}/files/DeleteFile`
+
+| Parameter | Type   | Required | Description                                 |
+|-----------|--------|----------|---------------------------------------------|
+| `file`    | string | yes      | Comma-separated list of file IDs to delete. |
+
+### Response
+
+| Parameter | Type        | Description                                                                      |
+|-----------|-------------|----------------------------------------------------------------------------------|
+| `status`  | boolean     | True if the request succeeded (all specified deletions succeeded).               |
+| `message` | string/null | Error message if something went wrong.                                           |
+| `deleted` | integer     | Number of files actually deleted.                                                |
+| `errors`  | string[]    | (Optional) Array of error strings explaining why specific file deletions failed. |
+
+## Delete Folder(s)
+
+```shell
+curl https://api.simplyprint.io/{id}/files/DeleteFolder?folder=123,456 \
+  -H 'accept: application/json' \
+  -H 'X-API-KEY: {API_KEY}'
+````
+
+> Success response
+
+```json
+{
+  "status": true,
+  "message": null,
+  "deleted": 2
+}
+```
+
+> Partial failure response (some folders deleted, some failed during removal)
+
+```json
+{
+  "status": false,
+  "message": "One or more folders failed to be deleted",
+  "deleted": 1,
+  "errors": [
+    "Failed to remove folder with ID 456: underlying exception message"
+  ]
+}
+```
+
+> Failure response: no folder IDs specified
+
+```json
+{
+  "status": false,
+  "message": "No file ID(s) specified"
+}
+```
+
+> Failure response: folder does not exist or not modifiable (either because it’s missing or the user lacks permission)
+
+```json
+{
+  "status": false,
+  "message": "One or more folders do not exist"
+}
+```
+
+This endpoint deletes one or more folders. All specified folder IDs must exist and be modifiable by the requesting user;
+if existence or permission validation fails up front, the request fails immediately. If some deletions fail during
+removal, those errors are returned while successful deletions are counted.
+
+### Request
+
+`GET /{id}/files/DeleteFolder`
+
+| Parameter | Type   | Required | Description                                   |
+|-----------|--------|----------|-----------------------------------------------|
+| `folder`  | string | yes      | Comma-separated list of folder IDs to delete. |
+
+### Response
+
+| Parameter | Type        | Description                                                                              |
+|-----------|-------------|------------------------------------------------------------------------------------------|
+| `status`  | boolean     | True if the request succeeded (all specified deletions succeeded).                       |
+| `message` | string/null | `null` on full success; error message if something went wrong.                           |
+| `deleted` | integer     | Number of folders actually deleted.                                                      |
+| `errors`  | string\[]   | (Optional) Array of error strings explaining failures during deletion (partial failure). |