fix(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation

doc/compiled.json

@@ -6358,7 +6358,7 @@
     "/projects/{project_id}/figma_attachments/{figma_attachment_id}/keys": {
       "post": {
         "summary": "Attach the Figma attachment to a key",
-        "description": "Attach the Figma attachment to a key",
+        "description": "Links a translation key to a Figma attachment, creating a visual context association between a specific Phrase key and a Figma design frame. Use this when you want translators to see the on-screen region where a key's translation appears inside a Figma file.\n\nThe key-to-attachment relationship is modeled as a many-to-many join: a single Figma attachment can be linked to multiple keys, and a key can be linked to multiple Figma attachments. This endpoint requires the Attachable Screenshots feature to be enabled on the account.\n",
         "operationId": "figma_attachment/attach_to_key",
         "tags": [
           "Key's Figma attachments"
@@ -6374,40 +6374,80 @@
             "$ref": "#/components/parameters/figma_attachment_id"
           },
           {
-            "$ref": "#/components/parameters/id"
-          },
-          {
-            "description": "specify the branch to use",
-            "example": "my-feature-branch",
             "name": "branch",
             "in": "query",
+            "description": "specify the branch to use",
+            "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "example": "my-feature-branch"
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "title": "figma_attachment_keys/create/parameters",
+                "required": [
+                  "id"
+                ],
+                "properties": {
+                  "id": {
+                    "description": "ID of the translation key to attach to this Figma attachment.",
+                    "type": "string",
+                    "example": "abcd1234abcd1234abcd1234abcd1234"
+                  },
+                  "branch": {
+                    "description": "specify the branch to use",
+                    "type": "string",
+                    "example": "my-feature-branch"
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "204": {
-            "$ref": "#/components/responses/204"
+            "$ref": "#/components/responses/204",
+            "description": "The translation key was attached to the Figma attachment."
           },
           "400": {
-            "$ref": "#/components/responses/400"
+            "$ref": "#/components/responses/400",
+            "description": "Bad request: the request body is malformed or a required parameter is missing."
+          },
+          "401": {
+            "$ref": "#/components/responses/401",
+            "description": "Unauthorized: the access token is missing or invalid."
+          },
+          "403": {
+            "$ref": "#/components/responses/403",
+            "description": "Forbidden: the access token lacks the write scope, the requesting user does not hold manage permission on the Figma attachment or the translation key, or the account does not have the Attachable Screenshots feature enabled."
           },
           "404": {
-            "$ref": "#/components/responses/404"
+            "$ref": "#/components/responses/404",
+            "description": "Not found: the project, Figma attachment, or translation key does not exist under the given identifiers."
+          },
+          "422": {
+            "$ref": "#/components/responses/422",
+            "description": "Unprocessable entity: the translation key is already linked to this Figma attachment."
           },
           "429": {
-            "$ref": "#/components/responses/429"
+            "$ref": "#/components/responses/429",
+            "description": "Too many requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time before retrying."
           }
         },
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X POST \\\n  -F branch=my-feature-branch \\\n  -F id=key_id \\\n  -H 'Content-Type: application/json'"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys\" \\\n  -u USERNAME_OR_ACCESS_TOKEN \\\n  -X POST \\\n  -d '{\"id\":\"abcd1234abcd1234abcd1234abcd1234\",\"branch\":\"my-feature-branch\"}' \\\n  -H 'Content-Type: application/json' \\\n  -w \"\\nHTTP %{http_code}\""
           },
           {
             "lang": "CLI v2",
-            "source": "phrase figma_attachment attach_to_key \\\n--project_id <project_id> \\\n--figma_attachment_id <figma_attachment_id> \\\n--id <id> \\\n--branch my-feature-branch \\\n--access_token <token>"
+            "source": "phrase figma_attachments create \\\n--project_id <project_id> \\\n--figma_attachment_id <figma_attachment_id> \\\n--data '{\"id\":\"abcd1234abcd1234abcd1234abcd1234\",\"branch\":\"my-feature-branch\"}' \\\n--access_token <token>"
           }
         ],
         "x-cli-version": "2.13"

paths/figma_attachment_keys/create.yaml

@@ -1,44 +1,77 @@
 ---
 summary: Attach the Figma attachment to a key
-description: Attach the Figma attachment to a key
+description: |
+  Links a translation key to a Figma attachment, creating a visual context association between a specific Phrase key and a Figma design frame. Use this when you want translators to see the on-screen region where a key's translation appears inside a Figma file.
+
+  The key-to-attachment relationship is modeled as a many-to-many join: a single Figma attachment can be linked to multiple keys, and a key can be linked to multiple Figma attachments. This endpoint requires the Attachable Screenshots feature to be enabled on the account.
 operationId: figma_attachment/attach_to_key
 tags:
   - Key's Figma attachments
 parameters:
   - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP"
   - "$ref": "../../parameters.yaml#/project_id"
   - "$ref": "../../parameters.yaml#/figma_attachment_id"
-  - "$ref": "../../parameters.yaml#/id"
-  - description: specify the branch to use
-    example: my-feature-branch
-    name: branch
+  - name: branch
     in: query
+    description: specify the branch to use
+    required: false
     schema:
       type: string
+    example: my-feature-branch
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        type: object
+        title: figma_attachment_keys/create/parameters
+        required:
+          - id
+        properties:
+          id:
+            description: ID of the translation key to attach to this Figma attachment.
+            type: string
+            example: abcd1234abcd1234abcd1234abcd1234
+          branch:
+            description: specify the branch to use
+            type: string
+            example: my-feature-branch
 responses:
   "204":
     "$ref": "../../responses.yaml#/204"
+    description: The translation key was attached to the Figma attachment.
   "400":
     "$ref": "../../responses.yaml#/400"
+    description: "Bad request: the request body is malformed or a required parameter is missing."
+  "401":
+    "$ref": "../../responses.yaml#/401"
+    description: "Unauthorized: the access token is missing or invalid."
+  "403":
+    "$ref": "../../responses.yaml#/403"
+    description: "Forbidden: the access token lacks the write scope, the requesting user does not hold manage permission on the Figma attachment or the translation key, or the account does not have the Attachable Screenshots feature enabled."
   "404":
     "$ref": "../../responses.yaml#/404"
+    description: "Not found: the project, Figma attachment, or translation key does not exist under the given identifiers."
+  "422":
+    "$ref": "../../responses.yaml#/422"
+    description: "Unprocessable entity: the translation key is already linked to this Figma attachment."
   "429":
     "$ref": "../../responses.yaml#/429"
+    description: "Too many requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time before retrying."
 x-code-samples:
   - lang: Curl
     source: |-
       curl "https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys" \
         -u USERNAME_OR_ACCESS_TOKEN \
         -X POST \
-        -F branch=my-feature-branch \
-        -F id=key_id \
-        -H 'Content-Type: application/json'
+        -d '{"id":"abcd1234abcd1234abcd1234abcd1234","branch":"my-feature-branch"}' \
+        -H 'Content-Type: application/json' \
+        -w "\nHTTP %{http_code}"
   - lang: CLI v2
     source: |-
-      phrase figma_attachment attach_to_key \
+      phrase figma_attachments create \
       --project_id <project_id> \
       --figma_attachment_id <figma_attachment_id> \
-      --id <id> \
-      --branch my-feature-branch \
+      --data '{"id":"abcd1234abcd1234abcd1234abcd1234","branch":"my-feature-branch"}' \
       --access_token <token>
 x-cli-version: "2.13"