From a3b1097127d1d6752c9b623fbaf86933caf5b78e Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:55:18 +0200 Subject: [PATCH 1/2] 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/2] 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'