fix(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.\n",
         "operationId": "figma_attachment/detach_from_key",
         "tags": [
           "Key's Figma attachments"
@@ -6446,22 +6446,44 @@
         ],
         "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",
+            "description": "UNAUTHORIZED: no valid authentication credentials were provided."
+          },
+          "403": {
+            "$ref": "#/components/responses/403",
+            "description": "FIGMA_INTEGRATION_REQUIRED / INSUFFICIENT_SCOPE: the account does not have the Figma Screenshots feature enabled, the access token lacks the write scope, or the caller lacks manage permission on the key and the Figma attachment."
+          },
           "404": {
-            "$ref": "#/components/responses/404"
+            "$ref": "#/components/responses/404",
+            "description": "NOT_FOUND: the project, Figma attachment, or translation key does not exist."
+          },
+          "422": {
+            "$ref": "#/components/responses/422",
+            "description": "KEY_NOT_ATTACHED: the translation key is not currently linked to this Figma attachment."
           },
           "429": {
-            "$ref": "#/components/responses/429"
+            "$ref": "#/components/responses/429",
+            "description": "RATE_LIMIT_EXCEEDED: too many requests. Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying."
           }
         },
         "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"
           },
           {
             "lang": "CLI v2",

paths/figma_attachment_keys/destroy.yaml

@@ -1,6 +1,9 @@
 ---
 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.
 operationId: figma_attachment/detach_from_key
 tags:
   - Key's Figma attachments
@@ -17,21 +20,35 @@ 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"
+    description: "UNAUTHORIZED: no valid authentication credentials were provided."
+  "403":
+    "$ref": "../../responses.yaml#/403"
+    description: "FIGMA_INTEGRATION_REQUIRED / INSUFFICIENT_SCOPE: the account does not have the Figma Screenshots feature enabled, the access token lacks the write scope, or the caller lacks manage permission on the key and the Figma attachment."
   "404":
     "$ref": "../../responses.yaml#/404"
+    description: "NOT_FOUND: the project, Figma attachment, or translation key does not exist."
+  "422":
+    "$ref": "../../responses.yaml#/422"
+    description: "KEY_NOT_ATTACHED: the translation key is not currently linked to this Figma attachment."
   "429":
     "$ref": "../../responses.yaml#/429"
+    description: "RATE_LIMIT_EXCEEDED: too many requests. Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying."
 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
   - lang: CLI v2
     source: |-
       phrase figma_attachment detach_from_key \