diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..00a06e55 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21421,7 +21421,7 @@ }, "delete": { "summary": "Delete a screenshot", - "description": "Delete an existing screenshot.", + "description": "Permanently removes a screenshot and all its associated markers from the project. Use this when you need to fully remove a screenshot that is no longer relevant — for example, after a UI redesign renders the captured screen obsolete. This is a hard delete: the screenshot record and every key-to-region marker linked to it are destroyed together and cannot be recovered.\n", "operationId": "screenshot/delete", "tags": [ "Screenshots" @@ -21448,36 +21448,42 @@ ], "responses": { "204": { - "$ref": "#/components/responses/204" + "$ref": "#/components/responses/204", + "description": "The screenshot and all its markers were deleted successfully." }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "screenshot_invalid_request: The request was malformed or a path parameter failed validation." }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "screenshot_unauthorized: The access token is missing or invalid." }, "403": { "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to delete this screenshot, or when the account does not have the Attachable Screenshots feature." + "description": "screenshot_forbidden: The access token lacks the write scope, the account plan does not include the screenshot feature, or the user does not have manage permission on the screenshot." }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "screenshot_not_found: No screenshot with this identifier exists in the specified project." }, "422": { - "$ref": "#/components/responses/422" + "$ref": "#/components/responses/422", + "description": "screenshot_unprocessable: The screenshot could not be deleted due to validation errors. Inspect the errors array in the response body." }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "screenshot_rate_limited: The request was rate-limited. Wait until X-Rate-Limit-Reset before retrying." } }, "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE \\\n -d '{\"branch\":\"my-feature-branch\"}' \\\n -H 'Content-Type: application/json'" + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE" }, { "lang": "CLI v2", - "source": "phrase screenshots delete \\\n--project_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " + "source": "phrase screenshots delete \\\n --project_id \\\n --id \\\n --access_token " } ], "x-cli-version": "2.5" diff --git a/paths/screenshots/destroy.yaml b/paths/screenshots/destroy.yaml index df35b034..bd33e6c6 100644 --- a/paths/screenshots/destroy.yaml +++ b/paths/screenshots/destroy.yaml @@ -1,6 +1,7 @@ --- summary: Delete a screenshot -description: Delete an existing screenshot. +description: | + Permanently removes a screenshot and all its associated markers from the project. Use this when you need to fully remove a screenshot that is no longer relevant — for example, after a UI redesign renders the captured screen obsolete. This is a hard delete: the screenshot record and every key-to-region marker linked to it are destroyed together and cannot be recovered. operationId: screenshot/delete tags: - Screenshots @@ -17,32 +18,35 @@ parameters: responses: '204': "$ref": "../../responses.yaml#/204" + description: The screenshot and all its markers were deleted successfully. '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" + description: "screenshot_invalid_request: The request was malformed or a path parameter failed validation." '401': "$ref": "../../responses.yaml#/401" + description: "screenshot_unauthorized: The access token is missing or invalid." '403': "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to delete this screenshot, or when the account does not have the Attachable Screenshots feature. + description: "screenshot_forbidden: The access token lacks the write scope, the account plan does not include the screenshot feature, or the user does not have manage permission on the screenshot." + '404': + "$ref": "../../responses.yaml#/404" + description: "screenshot_not_found: No screenshot with this identifier exists in the specified project." '422': "$ref": "../../responses.yaml#/422" + description: "screenshot_unprocessable: The screenshot could not be deleted due to validation errors. Inspect the errors array in the response body." '429': "$ref": "../../responses.yaml#/429" + description: "screenshot_rate_limited: The request was rate-limited. Wait until X-Rate-Limit-Reset before retrying." x-code-samples: - lang: Curl source: |- curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ -u USERNAME_OR_ACCESS_TOKEN \ - -X DELETE \ - -d '{"branch":"my-feature-branch"}' \ - -H 'Content-Type: application/json' + -X DELETE - lang: CLI v2 source: |- phrase screenshots delete \ - --project_id \ - --id \ - --branch my-feature-branch \ - --access_token + --project_id \ + --id \ + --access_token x-cli-version: '2.5'