feat(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 deletes a screenshot from a Phrase Strings project. A screenshot\nis an image attached to one or more translation keys to provide visual context\nfor translators; it stores the filename, an optional name and description, and\nzero or more markers that map key regions to on-screen coordinates.\n\nUse this operation when a screenshot is no longer needed, has been superseded\nby an updated image, or should be removed before archiving a project.\n\n**Deletion is irreversible.** All screenshot markers (key associations) attached\nto the screenshot are removed as a cascade side effect. Translators who relied\non this screenshot for visual context will no longer see it. A `screenshots:delete`\nevent is dispatched after a successful deletion, which may trigger any configured\nwebhook subscriptions.\n\n**Pitfalls and constraints:**\n- The `id` path parameter is the screenshot's string code (a 32-character hex\n  string such as `d2e056aa9e70b01121f41693e344f5ee`), not a numeric database ID.\n- Requires the `write` OAuth scope. Calls with only a `read` scope receive 403.\n- The requesting user must have Manage permission on the Screenshot resource in\n  the project. Project Translators and Reviewers without Manage permission\n  receive 403.\n- The project must have the Attachable Screenshots feature enabled on the account\n  plan. Accounts without this feature receive 403.\n- Deletion on a protected project is blocked; the policy enforces\n  `!project.protected?` before granting Manage access.\n- If the screenshot code does not exist in the project, the loader raises\n  `ActiveRecord::RecordNotFound` and the endpoint returns 404.\n\n**Error codes:** Phrase Strings uses HTTP status codes as its machine-readable\nerror identifiers. No additional string error codes are returned. All error\nresponses include a `message` field and, where applicable, a `documentation_url`\nfield. Validation failure responses (422) additionally include an `errors` array\nwith per-field `resource`, `field`, and `message` entries.\n",
         "operationId": "screenshot/delete",
         "tags": [
           "Screenshots"
@@ -21437,18 +21437,30 @@
             "$ref": "#/components/parameters/id"
           },
           {
-            "description": "specify the branch to use",
+            "description": "Name of the branch to operate on. When omitted, the operation targets the project's main (default) branch.",
             "example": "my-feature-branch",
             "name": "branch",
             "in": "query",
+            "required": false,
             "schema": {
               "type": "string"
             }
           }
         ],
         "responses": {
           "204": {
-            "$ref": "#/components/responses/204"
+            "description": "Screenshot deleted successfully. No response body is returned. The HTTP 204 No Content status confirms permanent removal.",
+            "headers": {
+              "X-Rate-Limit-Limit": {
+                "$ref": "#/components/headers/X-Rate-Limit-Limit"
+              },
+              "X-Rate-Limit-Remaining": {
+                "$ref": "#/components/headers/X-Rate-Limit-Remaining"
+              },
+              "X-Rate-Limit-Reset": {
+                "$ref": "#/components/headers/X-Rate-Limit-Reset"
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/400"
@@ -21458,10 +21470,11 @@
           },
           "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": "Forbidden. Returned in three cases: (1) The access token was issued with the `read` scope only — re-authorize with the `write` scope. (2) The requesting user does not have Manage permission on the Screenshot resource in this project — contact a project Owner or Admin to grant the required role. (3) The account plan does not include the Attachable Screenshots feature — upgrade the plan or contact Phrase support."
           },
           "404": {
-            "$ref": "#/components/responses/404"
+            "$ref": "#/components/responses/404",
+            "description": "Not found. The `project_id` or screenshot `id` does not correspond to an existing record accessible to the authenticated user. Verify both values and retry."
           },
           "422": {
             "$ref": "#/components/responses/422"
@@ -21473,11 +21486,11 @@
         "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\n\n# With an optional branch query parameter:\ncurl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE\n\n# Expected response: HTTP 204 No Content (empty body)"
           },
           {
             "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 d2e056aa9e70b01121f41693e344f5ee \\\n--branch my-feature-branch \\\n--access_token <token>\n\n# Expected response: HTTP 204 No Content (empty body)"
           }
         ],
         "x-cli-version": "2.5"

paths/screenshots/destroy.yaml

@@ -1,31 +1,88 @@
 ---
 summary: Delete a screenshot
-description: Delete an existing screenshot.
+description: |
+  Permanently deletes a screenshot from a Phrase Strings project. A screenshot
+  is an image attached to one or more translation keys to provide visual context
+  for translators; it stores the filename, an optional name and description, and
+  zero or more markers that map key regions to on-screen coordinates.
+
+  Use this operation when a screenshot is no longer needed, has been superseded
+  by an updated image, or should be removed before archiving a project.
+
+  **Deletion is irreversible.** All screenshot markers (key associations) attached
+  to the screenshot are removed as a cascade side effect. Translators who relied
+  on this screenshot for visual context will no longer see it. A `screenshots:delete`
+  event is dispatched after a successful deletion, which may trigger any configured
+  webhook subscriptions.
+
+  **Pitfalls and constraints:**
+  - The `id` path parameter is the screenshot's string code (a 32-character hex
+    string such as `d2e056aa9e70b01121f41693e344f5ee`), not a numeric database ID.
+  - Requires the `write` OAuth scope. Calls with only a `read` scope receive 403.
+  - The requesting user must have Manage permission on the Screenshot resource in
+    the project. Project Translators and Reviewers without Manage permission
+    receive 403.
+  - The project must have the Attachable Screenshots feature enabled on the account
+    plan. Accounts without this feature receive 403.
+  - Deletion on a protected project is blocked; the policy enforces
+    `!project.protected?` before granting Manage access.
+  - If the screenshot code does not exist in the project, the loader raises
+    `ActiveRecord::RecordNotFound` and the endpoint returns 404.
+
+  **Error codes:** Phrase Strings uses HTTP status codes as its machine-readable
+  error identifiers. No additional string error codes are returned. All error
+  responses include a `message` field and, where applicable, a `documentation_url`
+  field. Validation failure responses (422) additionally include an `errors` array
+  with per-field `resource`, `field`, and `message` entries.
 operationId: screenshot/delete
 tags:
 - Screenshots
 parameters:
 - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
 - "$ref": "../../parameters.yaml#/project_id"
 - "$ref": "../../parameters.yaml#/id"
-- description: specify the branch to use
+- description: >-
+    Name of the branch to operate on. When omitted, the operation targets the
+    project's main (default) branch.
   example: my-feature-branch
   name: branch
   in: query
+  required: false
   schema:
     type: string
 responses:
   '204':
-    "$ref": "../../responses.yaml#/204"
+    description: >-
+      Screenshot deleted successfully. No response body is returned. The
+      HTTP 204 No Content status confirms permanent removal.
+    headers:
+      X-Rate-Limit-Limit:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Limit"
+      X-Rate-Limit-Remaining:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining"
+      X-Rate-Limit-Reset:
+        "$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
   '400':
     "$ref": "../../responses.yaml#/400"
-  '404':
-    "$ref": "../../responses.yaml#/404"
   '401':
     "$ref": "../../responses.yaml#/401"
   '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: >-
+      Forbidden. Returned in three cases:
+      (1) The access token was issued with the `read` scope only — re-authorize
+      with the `write` scope.
+      (2) The requesting user does not have Manage permission on the Screenshot
+      resource in this project — contact a project Owner or Admin to grant the
+      required role.
+      (3) The account plan does not include the Attachable Screenshots feature —
+      upgrade the plan or contact Phrase support.
+  '404':
+    "$ref": "../../responses.yaml#/404"
+    description: >-
+      Not found. The `project_id` or screenshot `id` does not correspond to an
+      existing record accessible to the authenticated user. Verify both values
+      and retry.
   '422':
     "$ref": "../../responses.yaml#/422"
   '429':
@@ -35,14 +92,21 @@ x-code-samples:
   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
+
+    # With an optional branch query parameter:
+    curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch" \
+      -u USERNAME_OR_ACCESS_TOKEN \
+      -X DELETE
+
+    # Expected response: HTTP 204 No Content (empty body)
 - lang: CLI v2
   source: |-
     phrase screenshots delete \
     --project_id <project_id> \
-    --id <id> \
+    --id d2e056aa9e70b01121f41693e344f5ee \
     --branch my-feature-branch \
     --access_token <token>
+
+    # Expected response: HTTP 204 No Content (empty body)
 x-cli-version: '2.5'