From a3b1097127d1d6752c9b623fbaf86933caf5b78e Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:55:18 +0200 Subject: [PATCH 1/4] feat(API): improve delete /projects/{project_id}/documents/{id} documentation --- doc/compiled.json | 16 +++++++++++----- paths/documents/destroy.yaml | 26 +++++++++++++++++--------- 2 files changed, 28 insertions(+), 14 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..0e408699 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5684,7 +5684,7 @@ "/projects/{project_id}/documents/{id}": { "delete": { "summary": "Delete document", - "description": "Delete an existing document.", + "description": "Permanently deletes a document and all of its associated translation segments from the project. Use this when you want to remove a document that is no longer needed; the deletion cannot be reversed and all associated segments will be lost.\n\nRequires the write scope on the access token and manage permission on the document. Returns 403 when either condition is not met.\n", "operationId": "document/delete", "tags": [ "Documents" @@ -5702,36 +5702,42 @@ ], "responses": { "200": { + "description": "The document was successfully deleted. The response body is empty.", "$ref": "#/components/responses/200" }, "400": { + "description": "Bad request. The request was malformed or contained an invalid parameter. Correct the request and retry.", "$ref": "#/components/responses/400" }, "401": { + "description": "Unauthorized. The access token is missing or invalid. Provide a valid token and retry.", "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to delete this document." + "description": "Forbidden. The access token lacks the write scope or the authenticated user does not have manage permission on this document. Obtain a token with the write scope or request manage access from a project administrator.", + "$ref": "#/components/responses/403" }, "404": { + "description": "Not Found. No document with the given ID exists in this project. Verify the document ID and project ID before retrying.", "$ref": "#/components/responses/404" }, "422": { + "description": "Unprocessable entity. The document could not be deleted due to a validation error. Check the errors field in the response body for details.", "$ref": "#/components/responses/422" }, "429": { + "description": "Rate limit exceeded. Too many requests in a short period. Wait until the time indicated by the X-Rate-Limit-Reset header before retrying.", "$ref": "#/components/responses/429" } }, "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents/: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/documents/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE" }, { "lang": "CLI v2", - "source": "phrase documents delete \\\n--project_id \\\n--id \\\n--access_token " + "source": "phrase documents delete \\\n--project_id my-project-xyz123 \\\n--id doc-abc456 \\\n--access_token USERNAME_OR_ACCESS_TOKEN" } ], "x-cli-version": "2.5" diff --git a/paths/documents/destroy.yaml b/paths/documents/destroy.yaml index bcae3e6e..2b69987e 100644 --- a/paths/documents/destroy.yaml +++ b/paths/documents/destroy.yaml @@ -1,6 +1,9 @@ --- summary: Delete document -description: Delete an existing document. +description: | + Permanently deletes a document and all of its associated translation segments from the project. Use this when you want to remove a document that is no longer needed; the deletion cannot be reversed and all associated segments will be lost. + + Requires the write scope on the access token and manage permission on the document. Returns 403 when either condition is not met. operationId: document/delete tags: - Documents @@ -10,31 +13,36 @@ parameters: - "$ref": "../../parameters.yaml#/id" responses: '200': + description: The document was successfully deleted. The response body is empty. "$ref": "../../responses.yaml#/200" '400': + description: Bad request. The request was malformed or contained an invalid parameter. Correct the request and retry. "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" '401': + description: Unauthorized. The access token is missing or invalid. Provide a valid token and retry. "$ref": "../../responses.yaml#/401" '403': + description: Forbidden. The access token lacks the write scope or the authenticated user does not have manage permission on this document. Obtain a token with the write scope or request manage access from a project administrator. "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `write` scope or when the requesting user is not allowed to delete this document. + '404': + description: Not Found. No document with the given ID exists in this project. Verify the document ID and project ID before retrying. + "$ref": "../../responses.yaml#/404" '422': + description: Unprocessable entity. The document could not be deleted due to a validation error. Check the errors field in the response body for details. "$ref": "../../responses.yaml#/422" '429': + description: Rate limit exceeded. Too many requests in a short period. Wait until the time indicated by the X-Rate-Limit-Reset header before retrying. "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl source: |- curl "https://api.phrase.com/v2/projects/:project_id/documents/:id" \ -u USERNAME_OR_ACCESS_TOKEN \ - -X DELETE \ - -H 'Content-Type: application/json' + -X DELETE - lang: CLI v2 source: |- phrase documents delete \ - --project_id \ - --id \ - --access_token + --project_id my-project-xyz123 \ + --id doc-abc456 \ + --access_token USERNAME_OR_ACCESS_TOKEN x-cli-version: '2.5' From c53b2fc497792061b2a2d2ae62e49060e890c080 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 20:56:43 +0100 Subject: [PATCH 2/4] docs(API): address review on delete /projects/{project_id}/documents/{id} - CLI v2 sample: replace slug-like example values (my-project-xyz123, doc-abc456) with the / placeholders used by every other endpoint, and fix --access_token to take rather than a username (a username will not authenticate). (theSoenke) - Drop the scope/permission sentence from the top-level description; the 403 response already documents the write-scope and manage-permission requirement. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 4 ++-- paths/documents/destroy.yaml | 8 +++----- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 0e408699..ea3ec9af 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5684,7 +5684,7 @@ "/projects/{project_id}/documents/{id}": { "delete": { "summary": "Delete document", - "description": "Permanently deletes a document and all of its associated translation segments from the project. Use this when you want to remove a document that is no longer needed; the deletion cannot be reversed and all associated segments will be lost.\n\nRequires the write scope on the access token and manage permission on the document. Returns 403 when either condition is not met.\n", + "description": "Permanently deletes a document and all of its associated translation segments from the project. Use this when you want to remove a document that is no longer needed; the deletion cannot be reversed and all associated segments will be lost.\n", "operationId": "document/delete", "tags": [ "Documents" @@ -5737,7 +5737,7 @@ }, { "lang": "CLI v2", - "source": "phrase documents delete \\\n--project_id my-project-xyz123 \\\n--id doc-abc456 \\\n--access_token USERNAME_OR_ACCESS_TOKEN" + "source": "phrase documents delete \\\n--project_id \\\n--id \\\n--access_token " } ], "x-cli-version": "2.5" diff --git a/paths/documents/destroy.yaml b/paths/documents/destroy.yaml index 2b69987e..5bebd2ef 100644 --- a/paths/documents/destroy.yaml +++ b/paths/documents/destroy.yaml @@ -2,8 +2,6 @@ summary: Delete document description: | Permanently deletes a document and all of its associated translation segments from the project. Use this when you want to remove a document that is no longer needed; the deletion cannot be reversed and all associated segments will be lost. - - Requires the write scope on the access token and manage permission on the document. Returns 403 when either condition is not met. operationId: document/delete tags: - Documents @@ -42,7 +40,7 @@ x-code-samples: - lang: CLI v2 source: |- phrase documents delete \ - --project_id my-project-xyz123 \ - --id doc-abc456 \ - --access_token USERNAME_OR_ACCESS_TOKEN + --project_id \ + --id \ + --access_token x-cli-version: '2.5' From 4b2d452657c0b180cd2e7a6a9adb128b6f1acef5 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:09:35 +0200 Subject: [PATCH 3/4] 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 | 7 ------- paths/documents/destroy.yaml | 7 ------- 2 files changed, 14 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index ea3ec9af..17a8e3ee 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5702,31 +5702,24 @@ ], "responses": { "200": { - "description": "The document was successfully deleted. The response body is empty.", "$ref": "#/components/responses/200" }, "400": { - "description": "Bad request. The request was malformed or contained an invalid parameter. Correct the request and retry.", "$ref": "#/components/responses/400" }, "401": { - "description": "Unauthorized. The access token is missing or invalid. Provide a valid token and retry.", "$ref": "#/components/responses/401" }, "403": { - "description": "Forbidden. The access token lacks the write scope or the authenticated user does not have manage permission on this document. Obtain a token with the write scope or request manage access from a project administrator.", "$ref": "#/components/responses/403" }, "404": { - "description": "Not Found. No document with the given ID exists in this project. Verify the document ID and project ID before retrying.", "$ref": "#/components/responses/404" }, "422": { - "description": "Unprocessable entity. The document could not be deleted due to a validation error. Check the errors field in the response body for details.", "$ref": "#/components/responses/422" }, "429": { - "description": "Rate limit exceeded. Too many requests in a short period. Wait until the time indicated by the X-Rate-Limit-Reset header before retrying.", "$ref": "#/components/responses/429" } }, diff --git a/paths/documents/destroy.yaml b/paths/documents/destroy.yaml index 5bebd2ef..2c25bf07 100644 --- a/paths/documents/destroy.yaml +++ b/paths/documents/destroy.yaml @@ -11,25 +11,18 @@ parameters: - "$ref": "../../parameters.yaml#/id" responses: '200': - description: The document was successfully deleted. The response body is empty. "$ref": "../../responses.yaml#/200" '400': - description: Bad request. The request was malformed or contained an invalid parameter. Correct the request and retry. "$ref": "../../responses.yaml#/400" '401': - description: Unauthorized. The access token is missing or invalid. Provide a valid token and retry. "$ref": "../../responses.yaml#/401" '403': - description: Forbidden. The access token lacks the write scope or the authenticated user does not have manage permission on this document. Obtain a token with the write scope or request manage access from a project administrator. "$ref": "../../responses.yaml#/403" '404': - description: Not Found. No document with the given ID exists in this project. Verify the document ID and project ID before retrying. "$ref": "../../responses.yaml#/404" '422': - description: Unprocessable entity. The document could not be deleted due to a validation error. Check the errors field in the response body for details. "$ref": "../../responses.yaml#/422" '429': - description: Rate limit exceeded. Too many requests in a short period. Wait until the time indicated by the X-Rate-Limit-Reset header before retrying. "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl From 1d872472888020ebba9ed1146c23d3b90bff9961 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 10:28:17 +0200 Subject: [PATCH 4/4] 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/documents/destroy.yaml | 12 ------------ 2 files changed, 22 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 17a8e3ee..a73ac25a 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5723,16 +5723,6 @@ "$ref": "#/components/responses/429" } }, - "x-code-samples": [ - { - "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE" - }, - { - "lang": "CLI v2", - "source": "phrase documents delete \\\n--project_id \\\n--id \\\n--access_token " - } - ], "x-cli-version": "2.5" } }, diff --git a/paths/documents/destroy.yaml b/paths/documents/destroy.yaml index 2c25bf07..f785e3d4 100644 --- a/paths/documents/destroy.yaml +++ b/paths/documents/destroy.yaml @@ -24,16 +24,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/documents/:id" \ - -u USERNAME_OR_ACCESS_TOKEN \ - -X DELETE -- lang: CLI v2 - source: |- - phrase documents delete \ - --project_id \ - --id \ - --access_token x-cli-version: '2.5'