From 40b3fb914b0b4abdab2dae78992548252837afce Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:51:54 +0200 Subject: [PATCH 1/2] feat(API): improve post /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys documentation --- doc/compiled.json | 51 +++++++++++++++++++---- paths/figma_attachment_keys/create.yaml | 55 ++++++++++++++++++++----- 2 files changed, 87 insertions(+), 19 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090c..fcfb759b0 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": "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. Returns 422 when the key is already linked to this Figma attachment. This endpoint requires the Attachable Screenshots feature to be enabled on the account. The requesting user must hold manage permission on both the Figma attachment and the translation key.\n\nErrors:\n\n- 400 Bad Request: the request body is malformed or a required parameter is missing. Correct the request body and retry.\n- 401 Unauthorized: the access token is missing or invalid. Supply a valid token with the write scope.\n- 403 Forbidden: returned when the access token lacks the write scope, when the requesting user does not hold manage permission on the Figma attachment or on the translation key, or when the account does not have the Attachable Screenshots feature enabled. Check the token's scopes and the user's project permissions.\n- 404 Not Found: the project, Figma attachment, or translation key does not exist under the given identifiers. Verify each ID in the request path and body.\n- 422 Unprocessable Entity: the translation key is already linked to this Figma attachment. The response body contains a machine-readable message field (\"Already attached\") identifying the conflict. Remove the duplicate request or detach the key first if re-attachment is intended.\n- 429 Too Many Requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time indicated in the response headers before retrying.\n", "operationId": "figma_attachment/attach_to_key", "tags": [ "Key's Figma attachments" @@ -6374,18 +6374,42 @@ "$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": "Name of the branch to use. When omitted, the main (default) branch is used.", + "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": "Name of the branch to use. When omitted, the main (default) branch is used.", + "type": "string", + "example": "my-feature-branch" + } + } + } + } + } + }, "responses": { "204": { "$ref": "#/components/responses/204" @@ -6393,9 +6417,18 @@ "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" } @@ -6403,11 +6436,11 @@ "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 \\\n--figma_attachment_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " + "source": "phrase figma_attachment attach_to_key \\\n--project_id \\\n--figma_attachment_id \\\n--data '{\"id\":\"abcd1234abcd1234abcd1234abcd1234\",\"branch\":\"my-feature-branch\"}' \\\n--access_token " } ], "x-cli-version": "2.13" diff --git a/paths/figma_attachment_keys/create.yaml b/paths/figma_attachment_keys/create.yaml index b2d3e054f..fc6d36876 100644 --- a/paths/figma_attachment_keys/create.yaml +++ b/paths/figma_attachment_keys/create.yaml @@ -1,6 +1,18 @@ --- 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. Returns 422 when the key is already linked to this Figma attachment. This endpoint requires the Attachable Screenshots feature to be enabled on the account. The requesting user must hold manage permission on both the Figma attachment and the translation key. + + Errors: + + - 400 Bad Request: the request body is malformed or a required parameter is missing. Correct the request body and retry. + - 401 Unauthorized: the access token is missing or invalid. Supply a valid token with the write scope. + - 403 Forbidden: returned when the access token lacks the write scope, when the requesting user does not hold manage permission on the Figma attachment or on the translation key, or when the account does not have the Attachable Screenshots feature enabled. Check the token's scopes and the user's project permissions. + - 404 Not Found: the project, Figma attachment, or translation key does not exist under the given identifiers. Verify each ID in the request path and body. + - 422 Unprocessable Entity: the translation key is already linked to this Figma attachment. The response body contains a machine-readable message field ("Already attached") identifying the conflict. Remove the duplicate request or detach the key first if re-attachment is intended. + - 429 Too Many Requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time indicated in the response headers before retrying. operationId: figma_attachment/attach_to_key tags: - Key's Figma attachments @@ -8,20 +20,44 @@ 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: Name of the branch to use. When omitted, the main (default) branch is used. + 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: Name of the branch to use. When omitted, the main (default) branch is used. + 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: @@ -30,15 +66,14 @@ 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' + -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 \ --project_id \ --figma_attachment_id \ - --id \ - --branch my-feature-branch \ + --data '{"id":"abcd1234abcd1234abcd1234abcd1234","branch":"my-feature-branch"}' \ --access_token x-cli-version: "2.13" From bb59c1ee1dc28b28fc4109300f3559aace4e1f62 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 20:59:16 +0100 Subject: [PATCH 2/2] fix(API): address review on post .../figma_attachments/{figma_attachment_id}/keys - Move the per-status prose out of the top-level description and onto the response objects (the pattern from #1182), removing the 'Errors:' block and the inline 'Returns 422 ...' sentence. (theSoenke) - Normalize the branch parameter (query + body) to 'specify the branch to use', matching the wording used across the rest of the API rather than a bespoke 'When omitted, the main (default) branch is used.' (theSoenke) - Fix the CLI v2 command: 'phrase figma_attachments create', not the non-existent 'phrase figma_attachment attach_to_key'. (theSoenke) Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 29 +++++++++++++++---------- paths/figma_attachment_keys/create.yaml | 24 ++++++++++---------- 2 files changed, 29 insertions(+), 24 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index fcfb759b0..3e261083c 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": "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. Returns 422 when the key is already linked to this Figma attachment. This endpoint requires the Attachable Screenshots feature to be enabled on the account. The requesting user must hold manage permission on both the Figma attachment and the translation key.\n\nErrors:\n\n- 400 Bad Request: the request body is malformed or a required parameter is missing. Correct the request body and retry.\n- 401 Unauthorized: the access token is missing or invalid. Supply a valid token with the write scope.\n- 403 Forbidden: returned when the access token lacks the write scope, when the requesting user does not hold manage permission on the Figma attachment or on the translation key, or when the account does not have the Attachable Screenshots feature enabled. Check the token's scopes and the user's project permissions.\n- 404 Not Found: the project, Figma attachment, or translation key does not exist under the given identifiers. Verify each ID in the request path and body.\n- 422 Unprocessable Entity: the translation key is already linked to this Figma attachment. The response body contains a machine-readable message field (\"Already attached\") identifying the conflict. Remove the duplicate request or detach the key first if re-attachment is intended.\n- 429 Too Many Requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time indicated in the response headers before retrying.\n", + "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" @@ -6376,7 +6376,7 @@ { "name": "branch", "in": "query", - "description": "Name of the branch to use. When omitted, the main (default) branch is used.", + "description": "specify the branch to use", "required": false, "schema": { "type": "string" @@ -6401,7 +6401,7 @@ "example": "abcd1234abcd1234abcd1234abcd1234" }, "branch": { - "description": "Name of the branch to use. When omitted, the main (default) branch is used.", + "description": "specify the branch to use", "type": "string", "example": "my-feature-branch" } @@ -6412,25 +6412,32 @@ }, "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" + "$ref": "#/components/responses/401", + "description": "Unauthorized: the access token is missing or invalid." }, "403": { - "$ref": "#/components/responses/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" + "$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": [ @@ -6440,7 +6447,7 @@ }, { "lang": "CLI v2", - "source": "phrase figma_attachment attach_to_key \\\n--project_id \\\n--figma_attachment_id \\\n--data '{\"id\":\"abcd1234abcd1234abcd1234abcd1234\",\"branch\":\"my-feature-branch\"}' \\\n--access_token " + "source": "phrase figma_attachments create \\\n--project_id \\\n--figma_attachment_id \\\n--data '{\"id\":\"abcd1234abcd1234abcd1234abcd1234\",\"branch\":\"my-feature-branch\"}' \\\n--access_token " } ], "x-cli-version": "2.13" diff --git a/paths/figma_attachment_keys/create.yaml b/paths/figma_attachment_keys/create.yaml index fc6d36876..c957f1adb 100644 --- a/paths/figma_attachment_keys/create.yaml +++ b/paths/figma_attachment_keys/create.yaml @@ -3,16 +3,7 @@ summary: 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. Returns 422 when the key is already linked to this Figma attachment. This endpoint requires the Attachable Screenshots feature to be enabled on the account. The requesting user must hold manage permission on both the Figma attachment and the translation key. - - Errors: - - - 400 Bad Request: the request body is malformed or a required parameter is missing. Correct the request body and retry. - - 401 Unauthorized: the access token is missing or invalid. Supply a valid token with the write scope. - - 403 Forbidden: returned when the access token lacks the write scope, when the requesting user does not hold manage permission on the Figma attachment or on the translation key, or when the account does not have the Attachable Screenshots feature enabled. Check the token's scopes and the user's project permissions. - - 404 Not Found: the project, Figma attachment, or translation key does not exist under the given identifiers. Verify each ID in the request path and body. - - 422 Unprocessable Entity: the translation key is already linked to this Figma attachment. The response body contains a machine-readable message field ("Already attached") identifying the conflict. Remove the duplicate request or detach the key first if re-attachment is intended. - - 429 Too Many Requests: the rate limit has been reached. Wait until the X-Rate-Limit-Reset time indicated in the response headers before retrying. + 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 @@ -22,7 +13,7 @@ parameters: - "$ref": "../../parameters.yaml#/figma_attachment_id" - name: branch in: query - description: Name of the branch to use. When omitted, the main (default) branch is used. + description: specify the branch to use required: false schema: type: string @@ -42,24 +33,31 @@ requestBody: type: string example: abcd1234abcd1234abcd1234abcd1234 branch: - description: Name of the branch to use. When omitted, the main (default) branch is used. + 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: |- @@ -71,7 +69,7 @@ x-code-samples: -w "\nHTTP %{http_code}" - lang: CLI v2 source: |- - phrase figma_attachment attach_to_key \ + phrase figma_attachments create \ --project_id \ --figma_attachment_id \ --data '{"id":"abcd1234abcd1234abcd1234abcd1234","branch":"my-feature-branch"}' \