feat(API): improve delete /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys/{id} documentation

doc/compiled.json

@@ -6416,7 +6416,7 @@
     "/projects/{project_id}/figma_attachments/{figma_attachment_id}/keys/{id}": {
       "delete": {
         "summary": "Detach the Figma attachment from a key",
-        "description": "Detach the Figma attachment from a key",
+        "description": "Removes the many-to-many association between a translation key and a Figma attachment. Neither the translation key nor the Figma attachment is deleted — only the link between them is removed. Use this when a key no longer corresponds to the design element represented by the Figma frame, or when cleaning up stale key associations after a design update.\n\nThis endpoint is only available on plans that include the Figma Screenshots feature. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment.\n\nReturns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed.\n\n**Errors**\n\n| Code | Status | Cause | Remediation |\n|---|---|---|---|\n| `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. |\n| `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. |\n| `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. |\n| `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. |\n| `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. |\n| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. |\n",
         "operationId": "figma_attachment/detach_from_key",
         "tags": [
           "Key's Figma attachments"
@@ -6446,22 +6446,39 @@
         ],
         "responses": {
           "204": {
-            "$ref": "#/components/responses/204"
+            "description": "The key was successfully detached from the Figma attachment. No content is returned.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "title": "figma_attachment_keys/destroy/response"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/400"
           },
+          "401": {
+            "$ref": "#/components/responses/401"
+          },
+          "403": {
+            "$ref": "#/components/responses/403"
+          },
           "404": {
             "$ref": "#/components/responses/404"
           },
+          "422": {
+            "$ref": "#/components/responses/422"
+          },
           "429": {
             "$ref": "#/components/responses/429"
           }
         },
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE \\\n  -F branch=my-feature-branch \\\n  -H 'Content-Type: application/json'"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X DELETE\n\n# Expected response: HTTP 204 No Content (empty body)"
           },
           {
             "lang": "CLI v2",

paths/figma_attachment_keys/destroy.yaml

@@ -1,6 +1,22 @@
 ---
 summary: Detach the Figma attachment from a key
-description: Detach the Figma attachment from a key
+description: |
+  Removes the many-to-many association between a translation key and a Figma attachment. Neither the translation key nor the Figma attachment is deleted — only the link between them is removed. Use this when a key no longer corresponds to the design element represented by the Figma frame, or when cleaning up stale key associations after a design update.
+
+  This endpoint is only available on plans that include the Figma Screenshots feature. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment.
+
+  Returns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed.
+
+  **Errors**
+
+  | Code | Status | Cause | Remediation |
+  |---|---|---|---|
+  | `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. |
+  | `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. |
+  | `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. |
+  | `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. |
+  | `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. |
+  | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. |
 operationId: figma_attachment/detach_from_key
 tags:
   - Key's Figma attachments
@@ -17,21 +33,32 @@ parameters:
       type: string
 responses:
   "204":
-    "$ref": "../../responses.yaml#/204"
+    description: The key was successfully detached from the Figma attachment. No content is returned.
+    content:
+      application/json:
+        schema:
+          type: object
+          title: figma_attachment_keys/destroy/response
   "400":
     "$ref": "../../responses.yaml#/400"
+  "401":
+    "$ref": "../../responses.yaml#/401"
+  "403":
+    "$ref": "../../responses.yaml#/403"
   "404":
     "$ref": "../../responses.yaml#/404"
+  "422":
+    "$ref": "../../responses.yaml#/422"
   "429":
     "$ref": "../../responses.yaml#/429"
 x-code-samples:
   - lang: Curl
     source: |-
       curl "https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys/:id" \
         -u USERNAME_OR_ACCESS_TOKEN \
-        -X DELETE \
-        -F branch=my-feature-branch \
-        -H 'Content-Type: application/json'
+        -X DELETE
+
+      # Expected response: HTTP 204 No Content (empty body)
   - lang: CLI v2
     source: |-
       phrase figma_attachment detach_from_key \