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,42 +6374,65 @@
             "$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"
           },
           "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\" \\\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'"
-          },
-          {
-            "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>"
-          }
-        ],
         "x-cli-version": "2.13"
       }
     },

paths/figma_attachment_keys/create.yaml

@@ -1,44 +1,54 @@
 ---
 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"
   "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" \
-        -u USERNAME_OR_ACCESS_TOKEN \
-        -X POST \
-        -F branch=my-feature-branch \
-        -F id=key_id \
-        -H 'Content-Type: application/json'
-  - lang: CLI v2
-    source: |-
-      phrase figma_attachment attach_to_key \
-      --project_id <project_id> \
-      --figma_attachment_id <figma_attachment_id> \
-      --id <id> \
-      --branch my-feature-branch \
-      --access_token <token>
 x-cli-version: "2.13"