docs(API): improve delete /projects/{project_id}/screenshots/{id} documentation

doc/compiled.json

@@ -21421,7 +21421,7 @@
       },
       "delete": {
         "summary": "Delete a screenshot",
-        "description": "Delete an existing screenshot.",
+        "description": "Permanently removes a screenshot and all its associated markers from the project. Use this when you need to fully remove a screenshot that is no longer relevant — for example, after a UI redesign renders the captured screen obsolete. This is a hard delete: the screenshot record and every key-to-region marker linked to it are destroyed together and cannot be recovered.\n",
         "operationId": "screenshot/delete",
         "tags": [
           "Screenshots"
@@ -21448,36 +21448,42 @@
         ],
         "responses": {
           "204": {
-            "$ref": "#/components/responses/204"
+            "$ref": "#/components/responses/204",
+            "description": "The screenshot and all its markers were deleted successfully."
           },
           "400": {
-            "$ref": "#/components/responses/400"
+            "$ref": "#/components/responses/400",
+            "description": "screenshot_invalid_request: The request was malformed or a path parameter failed validation."
           },
           "401": {
-            "$ref": "#/components/responses/401"
+            "$ref": "#/components/responses/401",
+            "description": "screenshot_unauthorized: The access token is missing or invalid."
           },
           "403": {
             "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to delete this screenshot, or when the account does not have the Attachable Screenshots feature."
+            "description": "screenshot_forbidden: The access token lacks the write scope, the account plan does not include the screenshot feature, or the user does not have manage permission on the screenshot."
           },
           "404": {
-            "$ref": "#/components/responses/404"
+            "$ref": "#/components/responses/404",
+            "description": "screenshot_not_found: No screenshot with this identifier exists in the specified project."
           },
           "422": {
-            "$ref": "#/components/responses/422"
+            "$ref": "#/components/responses/422",
+            "description": "screenshot_unprocessable: The screenshot could not be deleted due to validation errors. Inspect the errors array in the response body."
           },
           "429": {
-            "$ref": "#/components/responses/429"
+            "$ref": "#/components/responses/429",
+            "description": "screenshot_rate_limited: The request was rate-limited. Wait until X-Rate-Limit-Reset before retrying."
           }
         },
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE \\\n  -d '{\"branch\":\"my-feature-branch\"}' \\\n  -H 'Content-Type: application/json'"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE"
           },
           {
             "lang": "CLI v2",
-            "source": "phrase screenshots delete \\\n--project_id <project_id> \\\n--id <id> \\\n--branch my-feature-branch \\\n--access_token <token>"
+            "source": "phrase screenshots delete \\\n  --project_id <project_id> \\\n  --id <id> \\\n  --access_token <token>"
           }
         ],
         "x-cli-version": "2.5"

paths/screenshots/destroy.yaml

@@ -1,6 +1,7 @@
 ---
 summary: Delete a screenshot
-description: Delete an existing screenshot.
+description: |
+  Permanently removes a screenshot and all its associated markers from the project. Use this when you need to fully remove a screenshot that is no longer relevant — for example, after a UI redesign renders the captured screen obsolete. This is a hard delete: the screenshot record and every key-to-region marker linked to it are destroyed together and cannot be recovered.
 operationId: screenshot/delete
 tags:
 - Screenshots
@@ -17,32 +18,35 @@ parameters:
 responses:
   '204':
     "$ref": "../../responses.yaml#/204"
+    description: The screenshot and all its markers were deleted successfully.
   '400':
     "$ref": "../../responses.yaml#/400"
-  '404':
-    "$ref": "../../responses.yaml#/404"
+    description: "screenshot_invalid_request: The request was malformed or a path parameter failed validation."
   '401':
     "$ref": "../../responses.yaml#/401"
+    description: "screenshot_unauthorized: The access token is missing or invalid."
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to delete this screenshot, or when the account does not have the Attachable Screenshots feature.
+    description: "screenshot_forbidden: The access token lacks the write scope, the account plan does not include the screenshot feature, or the user does not have manage permission on the screenshot."
+  '404':
+    "$ref": "../../responses.yaml#/404"
+    description: "screenshot_not_found: No screenshot with this identifier exists in the specified project."
   '422':
     "$ref": "../../responses.yaml#/422"
+    description: "screenshot_unprocessable: The screenshot could not be deleted due to validation errors. Inspect the errors array in the response body."
   '429':
     "$ref": "../../responses.yaml#/429"
+    description: "screenshot_rate_limited: The request was rate-limited. Wait until X-Rate-Limit-Reset before retrying."
 x-code-samples:
 - lang: Curl
   source: |-
     curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
       -u USERNAME_OR_ACCESS_TOKEN \
-      -X DELETE \
-      -d '{"branch":"my-feature-branch"}' \
-      -H 'Content-Type: application/json'
+      -X DELETE
 - lang: CLI v2
   source: |-
     phrase screenshots delete \
-    --project_id <project_id> \
-    --id <id> \
-    --branch my-feature-branch \
-    --access_token <token>
+      --project_id <project_id> \
+      --id <id> \
+      --access_token <token>
 x-cli-version: '2.5'