From 96261707be783071cb37d8a60d695a69f4afbc24 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 10 Jun 2026 19:21:54 +0200 Subject: [PATCH] docs(API): improve POST figma_attachments/:id/keys documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds conceptual description (why/model/pitfalls), documents 401/403/422 responses with causes and remediation (feature gate, policy, duplicate attachment), improves branch parameter description, and fixes vocabulary. Part of DEVEX-118. 🤖 Generated with Claude Code (claude-sonnet-4-6) --- doc/compiled.json | 16 ++++++++++++--- paths/figma_attachment_keys/create.yaml | 26 ++++++++++++++++++++----- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index bf43680fa..813b3df9a 100644 --- a/doc/compiled.json +++ b/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": "Associates a Figma attachment with a translation key in the specified project, linking the design asset to the key for visual context during translation.\n\nUse this endpoint when you want to connect a Figma file — previously uploaded as a Figma attachment — to a specific translation key, so translators can see the design context for that string.\n\nThis operation is feature-gated: the `attachable_screenshots` feature must be enabled for the account. Attempting this call without the feature returns 403. The token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). Attaching the same Figma attachment to a key more than once returns 422 (\"Already attached\").\n\nPitfalls:\n- The `figma_attachment_id` must belong to the same project as `project_id`. Cross-project attachment is not supported and returns 404.\n- Protected projects block this operation even for manage-level users; 403 is returned.\n", "operationId": "figma_attachment/attach_to_key", "tags": [ "Key's Figma attachments" @@ -6377,7 +6377,7 @@ "$ref": "#/components/parameters/id" }, { - "description": "specify the branch to use", + "description": "Branch name to scope the key lookup to. When omitted, the main branch is used.", "example": "my-feature-branch", "name": "branch", "in": "query", @@ -6393,9 +6393,19 @@ "400": { "$ref": "#/components/responses/400" }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `write` scope, the account does not have the `attachable_screenshots` feature enabled, the user lacks manage permissions on the Figma attachment or key, or the project is protected.\n" + }, "404": { "$ref": "#/components/responses/404" }, + "422": { + "$ref": "#/components/responses/422" + }, "429": { "$ref": "#/components/responses/429" } @@ -6403,7 +6413,7 @@ "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 -H 'Content-Type: application/json' \\\n -d '{\"branch\":\"my-feature-branch\"}'" }, { "lang": "CLI v2", diff --git a/paths/figma_attachment_keys/create.yaml b/paths/figma_attachment_keys/create.yaml index b2d3e054f..cf7bc5cdd 100644 --- a/paths/figma_attachment_keys/create.yaml +++ b/paths/figma_attachment_keys/create.yaml @@ -1,6 +1,15 @@ --- summary: Attach the Figma attachment to a key -description: Attach the Figma attachment to a key +description: | + Associates a Figma attachment with a translation key in the specified project, linking the design asset to the key for visual context during translation. + + Use this endpoint when you want to connect a Figma file — previously uploaded as a Figma attachment — to a specific translation key, so translators can see the design context for that string. + + This operation is feature-gated: the `attachable_screenshots` feature must be enabled for the account. Attempting this call without the feature returns 403. The token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). Attaching the same Figma attachment to a key more than once returns 422 ("Already attached"). + + Pitfalls: + - The `figma_attachment_id` must belong to the same project as `project_id`. Cross-project attachment is not supported and returns 404. + - Protected projects block this operation even for manage-level users; 403 is returned. operationId: figma_attachment/attach_to_key tags: - Key's Figma attachments @@ -9,7 +18,7 @@ parameters: - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/figma_attachment_id" - "$ref": "../../parameters.yaml#/id" - - description: specify the branch to use + - description: Branch name to scope the key lookup to. When omitted, the main branch is used. example: my-feature-branch name: branch in: query @@ -20,8 +29,16 @@ responses: "$ref": "../../responses.yaml#/204" "400": "$ref": "../../responses.yaml#/400" + "401": + "$ref": "../../responses.yaml#/401" + "403": + "$ref": "../../responses.yaml#/403" + description: | + Forbidden. Returned when the access token lacks the `write` scope, the account does not have the `attachable_screenshots` feature enabled, the user lacks manage permissions on the Figma attachment or key, or the project is protected. "404": "$ref": "../../responses.yaml#/404" + "422": + "$ref": "../../responses.yaml#/422" "429": "$ref": "../../responses.yaml#/429" x-code-samples: @@ -30,9 +47,8 @@ x-code-samples: 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' + -H 'Content-Type: application/json' \ + -d '{"branch":"my-feature-branch"}' - lang: CLI v2 source: |- phrase figma_attachment attach_to_key \