From 69f490ee1b8649b675980f5f09e5e69bbfbb1f9b Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 10 Jun 2026 19:22:02 +0200 Subject: [PATCH 1/8] docs(API): improve DELETE figma_attachments/:id/keys/:id documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds conceptual description (why/model/pitfalls including that detach does not delete the attachment), documents 401/403/422 responses with causes and remediation (feature gate, policy, already-detached error), and improves branch parameter description. Part of DEVEX-118. 🤖 Generated with Claude Code (claude-sonnet-4-6) --- doc/compiled.json | 16 +++++++++++++--- paths/figma_attachment_keys/destroy.yaml | 22 +++++++++++++++++++--- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..1a0a9d8b 100644 --- a/doc/compiled.json +++ b/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 association between a Figma attachment and a translation key in the specified project.\n\nUse this endpoint when a design asset is no longer relevant to a translation key — for example, when a UI component has been redesigned and the old Figma frame no longer represents the string's context.\n\nThe token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). The `attachable_screenshots` feature must be enabled for the account. Attempting to detach an attachment that is not currently linked to the key returns 422 (\"Already detached\").\n\nPitfalls:\n- Detaching a Figma attachment does not delete the attachment itself from the project — it only removes the link to this key. The attachment remains in the project and can be re-attached.\n- Protected projects block this operation even for manage-level users; 403 is returned.\n", "operationId": "figma_attachment/detach_from_key", "tags": [ "Key's Figma attachments" @@ -6435,7 +6435,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", @@ -6451,9 +6451,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" } @@ -6461,7 +6471,7 @@ "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 \\\n -H 'Content-Type: application/json'" }, { "lang": "CLI v2", diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index 98961b0b..479e1a78 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -1,6 +1,15 @@ --- summary: Detach the Figma attachment from a key -description: Detach the Figma attachment from a key +description: | + Removes the association between a Figma attachment and a translation key in the specified project. + + Use this endpoint when a design asset is no longer relevant to a translation key — for example, when a UI component has been redesigned and the old Figma frame no longer represents the string's context. + + The token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). The `attachable_screenshots` feature must be enabled for the account. Attempting to detach an attachment that is not currently linked to the key returns 422 ("Already detached"). + + Pitfalls: + - Detaching a Figma attachment does not delete the attachment itself from the project — it only removes the link to this key. The attachment remains in the project and can be re-attached. + - Protected projects block this operation even for manage-level users; 403 is returned. operationId: figma_attachment/detach_from_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,7 +47,6 @@ x-code-samples: 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' - lang: CLI v2 source: |- From e01a59a2a9729b91603212170b4d1ba282432104 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:59:59 +0200 Subject: [PATCH 2/8] feat(API): improve delete /projects/{project_id}/figma_attachments/{figma_attachment_id}/keys/{id} documentation --- doc/compiled.json | 19 +++++++++---- paths/figma_attachment_keys/destroy.yaml | 35 ++++++++++++++++-------- 2 files changed, 36 insertions(+), 18 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 1a0a9d8b..e1dfad56 100644 --- a/doc/compiled.json +++ b/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": "Removes the association between a Figma attachment and a translation key in the specified project.\n\nUse this endpoint when a design asset is no longer relevant to a translation key — for example, when a UI component has been redesigned and the old Figma frame no longer represents the string's context.\n\nThe token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). The `attachable_screenshots` feature must be enabled for the account. Attempting to detach an attachment that is not currently linked to the key returns 422 (\"Already detached\").\n\nPitfalls:\n- Detaching a Figma attachment does not delete the attachment itself from the project — it only removes the link to this key. The attachment remains in the project and can be re-attached.\n- Protected projects block this operation even for manage-level users; 403 is returned.\n", + "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. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment.\n\nReturns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed.\n\n**Errors**\n\n| Code | Status | Cause | Remediation |\n|---|---|---|---|\n| `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. |\n| `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. |\n| `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. |\n| `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. |\n| `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. |\n| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. |\n", "operationId": "figma_attachment/detach_from_key", "tags": [ "Key's Figma attachments" @@ -6435,7 +6435,7 @@ "$ref": "#/components/parameters/id" }, { - "description": "Branch name to scope the key lookup to. When omitted, the main branch is used.", + "description": "specify the branch to use", "example": "my-feature-branch", "name": "branch", "in": "query", @@ -6446,7 +6446,15 @@ ], "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" @@ -6455,8 +6463,7 @@ "$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" + "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" @@ -6471,7 +6478,7 @@ "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 -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\n\n# Expected response: HTTP 204 No Content (empty body)" }, { "lang": "CLI v2", diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index 479e1a78..30d68d13 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -1,15 +1,22 @@ --- summary: Detach the Figma attachment from a key description: | - Removes the association between a Figma attachment and a translation key in the specified project. + 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. - Use this endpoint when a design asset is no longer relevant to a translation key — for example, when a UI component has been redesigned and the old Figma frame no longer represents the string's context. + This endpoint is only available on plans that include the Figma Screenshots feature. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment. - The token must have the `write` scope, and the authenticated user must have manage permissions on both the Figma attachment and the key (`FigmaAttachmentsTranslationKey`). The `attachable_screenshots` feature must be enabled for the account. Attempting to detach an attachment that is not currently linked to the key returns 422 ("Already detached"). + Returns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed. - Pitfalls: - - Detaching a Figma attachment does not delete the attachment itself from the project — it only removes the link to this key. The attachment remains in the project and can be re-attached. - - Protected projects block this operation even for manage-level users; 403 is returned. + **Errors** + + | Code | Status | Cause | Remediation | + |---|---|---|---| + | `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. | + | `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. | + | `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. | + | `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. | + | `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. | + | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. | operationId: figma_attachment/detach_from_key tags: - Key's Figma attachments @@ -18,7 +25,7 @@ parameters: - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/figma_attachment_id" - "$ref": "../../parameters.yaml#/id" - - description: Branch name to scope the key lookup to. When omitted, the main branch is used. + - description: specify the branch to use example: my-feature-branch name: branch in: query @@ -26,15 +33,18 @@ 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" "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": @@ -46,8 +56,9 @@ x-code-samples: source: |- curl "https://api.phrase.com/v2/projects/:project_id/figma_attachments/:figma_attachment_id/keys/:id" \ -u USERNAME_OR_ACCESS_TOKEN \ - -X DELETE \ - -H 'Content-Type: application/json' + -X DELETE + + # Expected response: HTTP 204 No Content (empty body) - lang: CLI v2 source: |- phrase figma_attachment detach_from_key \ From d338c5b34a26cf2bfdb68033f02c3614abb378be Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:10:21 +0100 Subject: [PATCH 3/8] fix(API): clean up delete .../figma_attachments/{figma_attachment_id}/keys/{id} Apply the batch review conventions: - Move the per-status 'Errors' table out of the top-level description and onto the response objects (401/403/404/422/429 now carry their own description), keeping only the endpoint purpose and feature-availability note in the description. - Drop the '# Expected response: HTTP 204 ...' trailer from the curl sample so it shows only the request. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 19 ++++++++++++------- paths/figma_attachment_keys/destroy.yaml | 22 ++++++---------------- 2 files changed, 18 insertions(+), 23 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index e1dfad56..c089eace 100644 --- a/doc/compiled.json +++ b/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": "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. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment.\n\nReturns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed.\n\n**Errors**\n\n| Code | Status | Cause | Remediation |\n|---|---|---|---|\n| `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. |\n| `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. |\n| `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. |\n| `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. |\n| `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. |\n| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. |\n", + "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" @@ -6460,25 +6460,30 @@ "$ref": "#/components/responses/400" }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "UNAUTHORIZED: no valid authentication credentials were provided." }, "403": { - "$ref": "#/components/responses/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" + "$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\n# Expected response: HTTP 204 No Content (empty body)" + "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", diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index 30d68d13..182ef6b6 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -3,20 +3,7 @@ summary: 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. Accounts without this feature enabled receive 403. Callers must hold manage permission on both the translation key and the Figma attachment. - - Returns 422 when the key is not currently linked to the specified Figma attachment. Verify the attachment is listed under the key before calling this endpoint; if the association no longer exists, no further action is needed. - - **Errors** - - | Code | Status | Cause | Remediation | - |---|---|---|---| - | `KEY_NOT_ATTACHED` | 422 | The translation key is not currently linked to this Figma attachment. | Confirm the attachment exists for the key before calling detach. | - | `FIGMA_INTEGRATION_REQUIRED` | 403 | The project account does not have the Figma Screenshots feature enabled. | Upgrade to a plan that includes Figma Screenshots or contact support. | - | `INSUFFICIENT_SCOPE` | 403 | The access token lacks the write scope required for this operation. | Re-authenticate with the write scope. | - | `UNAUTHORIZED` | 401 | No valid authentication credentials were provided. | Include a valid access token in the request. | - | `NOT_FOUND` | 404 | The project, Figma attachment, or translation key does not exist. | Verify all IDs in the request path are correct. | - | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests in a short period. | Wait for the interval indicated in the X-Rate-Limit-Reset header before retrying. | + This endpoint is only available on plans that include the Figma Screenshots feature. operationId: figma_attachment/detach_from_key tags: - Key's Figma attachments @@ -43,22 +30,25 @@ responses: "$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 - - # Expected response: HTTP 204 No Content (empty body) - lang: CLI v2 source: |- phrase figma_attachment detach_from_key \ From f69988ef04df6724fbd4cd43226e81965bc8fd18 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:08:36 +0200 Subject: [PATCH 4/8] docs(API): move error-response prose to shared responses.yaml Review feedback: error response descriptions should stay in the shared responses.yaml for consistency, not be re-authored inline per operation. Under OpenAPI 3.0 a description sibling of $ref is ignored anyway, so the inline text never rendered. Strip the inline $ref-sibling response descriptions (now bare $refs); the shared response owns the wording. Genuinely custom (non-$ref) response bodies are left intact. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 15 +++++---------- paths/figma_attachment_keys/destroy.yaml | 5 ----- 2 files changed, 5 insertions(+), 15 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index c089eace..e5f0fe48 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -6460,24 +6460,19 @@ "$ref": "#/components/responses/400" }, "401": { - "$ref": "#/components/responses/401", - "description": "UNAUTHORIZED: no valid authentication credentials were provided." + "$ref": "#/components/responses/401" }, "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." + "$ref": "#/components/responses/403" }, "404": { - "$ref": "#/components/responses/404", - "description": "NOT_FOUND: the project, Figma attachment, or translation key does not exist." + "$ref": "#/components/responses/404" }, "422": { - "$ref": "#/components/responses/422", - "description": "KEY_NOT_ATTACHED: the translation key is not currently linked to this Figma attachment." + "$ref": "#/components/responses/422" }, "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." + "$ref": "#/components/responses/429" } }, "x-code-samples": [ diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index 182ef6b6..bb71f0b0 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -30,19 +30,14 @@ responses: "$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: |- From 83d420712d3363dda28868346d6fda3912fbf5c1 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 10:29:42 +0200 Subject: [PATCH 5/8] docs(API): remove hand-written x-code-samples Strings convention: never hand-author Curl or CLI v2 samples. Mintlify renders the request sample (curl + the multi-language playground) and the response from the OpenAPI operation itself, so a hand-written x-code-samples block drifts and overrides the correct auto-generated one; a CLI v2 sample is not spec-derivable at all. Remove the block so Mintlify renders. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 10 ---------- paths/figma_attachment_keys/destroy.yaml | 14 -------------- 2 files changed, 24 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index e5f0fe48..0d8aaa23 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -6475,16 +6475,6 @@ "$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/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE" - }, - { - "lang": "CLI v2", - "source": "phrase figma_attachment detach_from_key \\\n--project_id \\\n--figma_attachment_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " - } - ], "x-cli-version": "2.13" } }, diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index bb71f0b0..15bbf673 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -38,18 +38,4 @@ responses: "$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/:id" \ - -u USERNAME_OR_ACCESS_TOKEN \ - -X DELETE - - lang: CLI v2 - source: |- - phrase figma_attachment detach_from_key \ - --project_id \ - --figma_attachment_id \ - --id \ - --branch my-feature-branch \ - --access_token x-cli-version: "2.13" From 1492855f640ab23c1e6632fa3df6e082aa22ff2c Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 29 Jun 2026 21:24:14 +0200 Subject: [PATCH 6/8] fix(API): keep CLI v2 code sample, only drop hand-written Curl New strings rubric rule: Mintlify auto-generates the request curl, so a hand-written Curl sample is redundant and overrides it, but a CLI v2 sample cannot be derived from the spec and must be preserved. This PR originally removed the whole x-code-samples block; restore the CLI v2 entry (Curl stays dropped). compiled.json regenerated via make bundle. --- doc/compiled.json | 6 ++++++ paths/figma_attachment_keys/destroy.yaml | 9 +++++++++ 2 files changed, 15 insertions(+) diff --git a/doc/compiled.json b/doc/compiled.json index 7a747f0a..0aa227df 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -6717,6 +6717,12 @@ "$ref": "#/components/responses/429" } }, + "x-code-samples": [ + { + "lang": "CLI v2", + "source": "phrase figma_attachment detach_from_key \\\n--project_id \\\n--figma_attachment_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " + } + ], "x-cli-version": "2.13" } }, diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index 15bbf673..aed90c3d 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -38,4 +38,13 @@ responses: "$ref": "../../responses.yaml#/422" "429": "$ref": "../../responses.yaml#/429" +x-code-samples: + - lang: CLI v2 + source: |- + phrase figma_attachment detach_from_key \ + --project_id \ + --figma_attachment_id \ + --id \ + --branch my-feature-branch \ + --access_token x-cli-version: "2.13" From 3036575311e26e9dcee6f237f3475d645f1818c0 Mon Sep 17 00:00:00 2001 From: Sven Dunemann Date: Wed, 1 Jul 2026 15:48:24 +0200 Subject: [PATCH 7/8] Update paths/figma_attachment_keys/destroy.yaml --- paths/figma_attachment_keys/destroy.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/paths/figma_attachment_keys/destroy.yaml b/paths/figma_attachment_keys/destroy.yaml index aed90c3d..a703384d 100644 --- a/paths/figma_attachment_keys/destroy.yaml +++ b/paths/figma_attachment_keys/destroy.yaml @@ -21,11 +21,6 @@ parameters: 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": "../../responses.yaml#/400" "401": From 5c7dfb3d6b2e7e28baa66e64698c23ec911a54c9 Mon Sep 17 00:00:00 2001 From: Sven Dunemann Date: Wed, 1 Jul 2026 15:52:43 +0200 Subject: [PATCH 8/8] Adjust compiled.json --- doc/compiled.json | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 0aa227df..0fd492eb 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -6688,15 +6688,7 @@ ], "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" - } - } - } + "description": "The key was successfully detached from the Figma attachment. No content is returned." }, "400": { "$ref": "#/components/responses/400"