From d0d2c0c60c871af0673b70580440e7ff6e40bf5f Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Tue, 9 Jun 2026 19:36:35 +0200 Subject: [PATCH 1/3] feat(API): improve DELETE /projects/{project_id}/screenshots/{id} documentation --- paths/screenshots/destroy.yaml | 139 +++++++++++++++++++++++++++++---- 1 file changed, 123 insertions(+), 16 deletions(-) diff --git a/paths/screenshots/destroy.yaml b/paths/screenshots/destroy.yaml index df35b034..bc1b1efe 100644 --- a/paths/screenshots/destroy.yaml +++ b/paths/screenshots/destroy.yaml @@ -1,48 +1,155 @@ --- summary: Delete a screenshot -description: Delete an existing screenshot. -operationId: screenshot/delete +description: | + Permanently deletes the screenshot identified by `id` from the project + identified by `project_id`. All translation-key markers attached to the + screenshot are removed as part of the deletion. Use this operation when a + screenshot is no longer needed or has been replaced by an updated image. + + **Parameters** + + | Name | In | Type | Required | Description | + |------|----|------|----------|-------------| + | X-PhraseApp-OTP | header | string | No | Two-factor authentication token. OTP (One-Time Password) value from your authenticator app, required only when 2FA is enabled on the account. | + | project_id | path | string | Yes | Unique string code identifying the project (for example, `3d7ce831a3e9e1b843dc16d36ee5b9f4`). | + | id | path | string | Yes | String code of the screenshot to delete (for example, `d2e056aa9e70b01121f41693e344f5ee`). This is the `id` field returned by the create, show, and list screenshot endpoints — it is not a numeric primary key. | + | branch | query | string | No | Name of the branch to use. When omitted the operation applies to the main project. | + + **Authorization:** Requires the `write` OAuth scope. The authenticated user + must have Manage permission on the Screenshot resource within the project. + + **Feature gate:** This endpoint is available only to accounts with the + Attachable Screenshots feature enabled. Requests from accounts on plans that + do not include this feature receive a 403 response with error code + `features_unavailable`. Requests originating from the Phrase Sketch Plugin + are additionally gated on the Sketch Plugin feature; accounts without that + feature also receive 403. + + **Cascade effect:** A successful deletion dispatches a `screenshots:delete` + event, which may trigger any configured webhook subscriptions for the project. + + **Validation failures (422):** If the underlying model destroy fails, the + response body contains a `message` string and an `errors` array with + per-field detail. Each entry in `errors` carries `resource`, `field`, and + `message`. + + **Errors** + + | Status | Error code | Cause | Resolution | + |--------|------------|-------|------------| + | 400 | `bad_request` | Malformed request parameters (for example, a branch name referencing a non-interactable branch). | Correct the request parameters and retry. | + | 401 | `unauthorized` | Authentication credentials are missing or invalid. | Supply a valid access token via `-u USERNAME:ACCESS_TOKEN` or the `Authorization` header. | + | 403 | `forbidden` | The access token lacks the `write` OAuth scope; the user account is unconfirmed; the authenticated user lacks Manage permission on the Screenshot resource; or the account does not have the Attachable Screenshots or Sketch Plugin feature enabled. | Use a token with the `write` scope, confirm the user account, or upgrade the subscription plan to one that includes Attachable Screenshots. | + | 404 | `not_found` | No screenshot with the given `id` exists in the specified project, or the `project_id` does not match any accessible project. | Verify both `project_id` and `id` using the list or show endpoints. | + | 422 | `unprocessable_entity` | The screenshot record could not be destroyed due to a model validation or database constraint failure. | Inspect the `errors` array in the response body for field-level detail. | + | 429 | `rate_limit_exceeded` | The request rate or concurrency limit for the access token has been exceeded. | Back off and retry after the interval indicated in the `X-Rate-Limit-Reset` response header. | +operationId: screenshots/delete tags: - Screenshots parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + name: X-PhraseApp-OTP + in: header + required: false + description: >- + OTP (One-Time Password) token from your authenticator app. Required only + when two-factor authentication is enabled on the account. + schema: + type: string - "$ref": "../../parameters.yaml#/project_id" + name: project_id + in: path + required: true + description: >- + Unique string code of the project (for example, + `3d7ce831a3e9e1b843dc16d36ee5b9f4`). + schema: + type: string - "$ref": "../../parameters.yaml#/id" -- description: specify the branch to use - example: my-feature-branch + name: id + in: path + required: true + description: >- + String code of the screenshot to delete (for example, + `d2e056aa9e70b01121f41693e344f5ee`). This is the `id` field returned by + the create, show, and list screenshot endpoints. + schema: + type: string + pattern: '^[0-9a-f]{32}$' +- "$ref": "../../parameters.yaml#/branch" name: branch in: query + required: false + description: >- + Name of the branch to use. When omitted the operation applies to the main + project. schema: type: string responses: '204': - "$ref": "../../responses.yaml#/204" + description: >- + The screenshot was deleted successfully. No response body is returned. + The HTTP status `204 No Content` confirms deletion. + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" + description: >- + Bad request. Returned when request parameters are malformed (for example, + referencing a non-interactable branch). Correct the request parameters + and retry. Error code: `bad_request`. '401': "$ref": "../../responses.yaml#/401" + description: >- + Unauthorized. Authentication credentials are missing or invalid. Supply a + valid access token. Error code: `unauthorized`. '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: >- + Forbidden. Returned when: the access token lacks the `write` OAuth scope; + the user account is unconfirmed; the authenticated user lacks Manage + permission on the Screenshot resource in this project; or the account + subscription does not include the Attachable Screenshots or Sketch Plugin + feature. To resolve: use a token with the `write` scope, confirm the user + account, or upgrade to a plan that includes Attachable Screenshots. + Error code: `forbidden` or `features_unavailable`. + '404': + "$ref": "../../responses.yaml#/404" + description: >- + Not found. No screenshot with the given `id` exists in the specified + project, or the `project_id` is invalid. Verify both identifiers using + the list or show endpoints. Error code: `not_found`. '422': "$ref": "../../responses.yaml#/422" + description: >- + Unprocessable entity. The screenshot record could not be destroyed due to + a model validation or constraint failure. Inspect the `errors` array in + the response body for field-level detail. Error code: + `unprocessable_entity`. '429': "$ref": "../../responses.yaml#/429" + description: >- + Too many requests. The request rate or concurrency limit has been + exceeded. Back off and retry after the interval indicated in the + `X-Rate-Limit-Reset` response header. Error code: `rate_limit_exceeded`. 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' + curl "https://api.phrase.com/v2/projects/3d7ce831a3e9e1b843dc16d36ee5b9f4/screenshots/d2e056aa9e70b01121f41693e344f5ee" \ + -u stephenlumenta:AbCdEf123456789xYzAbCdEf123456789xYz \ + -X DELETE + # Expected response: HTTP 204 No Content (empty body) - lang: CLI v2 source: |- phrase screenshots delete \ - --project_id \ - --id \ + --project_id 3d7ce831a3e9e1b843dc16d36ee5b9f4 \ + --id d2e056aa9e70b01121f41693e344f5ee \ --branch my-feature-branch \ - --access_token + --access_token AbCdEf123456789xYzAbCdEf123456789xYz + # Expected response: HTTP 204 No Content (empty body) x-cli-version: '2.5' From c44253f64ef670db45bb6e244366bef11a012fcc Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:56:33 +0200 Subject: [PATCH 2/3] feat(API): improve delete /projects/{project_id}/screenshots/{id} documentation --- doc/compiled.json | 38 ++++++--- paths/screenshots/destroy.yaml | 148 +++++++-------------------------- 2 files changed, 58 insertions(+), 128 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..64270ec5 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\nRequires manage permission on the screenshot and the write scope on the access token. Returns 403 if the account plan does not include the screenshot feature or if the access token lacks the write scope. Returns 404 if the screenshot does not exist in the specified project.\n\nErrors:\n\n- screenshot_invalid_request (400): The request was malformed or a path parameter failed validation. Correct the parameter format and retry.\n- screenshot_unauthorized (401): The access token is missing or invalid. Supply a valid access token.\n- screenshot_forbidden (403): The access token lacks the write scope, the account plan does not include the screenshot feature, or the requesting user does not have manage permission on the screenshot. Upgrade your plan, add the write scope to your token, or request manage access.\n- screenshot_not_found (404): No screenshot with this identifier exists in the project. Verify the project_id and id values.\n- screenshot_unprocessable (422): The screenshot could not be deleted because the model reported validation errors. Inspect the errors array in the response body.\n- screenshot_rate_limited (429): Too many requests have been made. Wait until the X-Rate-Limit-Reset time before retrying.\n", "operationId": "screenshot/delete", "tags": [ "Screenshots" @@ -21448,39 +21448,55 @@ ], "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\n\nHTTP/1.1 204 No Content" }, { "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" + "x-cli-version": "2.5", + "security": [ + { + "Token": [] + }, + { + "OAuth2": [ + "write" + ] + } + ] } }, "/accounts/{account_id}/glossaries/{glossary_id}/terms": { diff --git a/paths/screenshots/destroy.yaml b/paths/screenshots/destroy.yaml index bc1b1efe..50d3312a 100644 --- a/paths/screenshots/destroy.yaml +++ b/paths/screenshots/destroy.yaml @@ -1,155 +1,69 @@ --- summary: Delete a screenshot description: | - Permanently deletes the screenshot identified by `id` from the project - identified by `project_id`. All translation-key markers attached to the - screenshot are removed as part of the deletion. Use this operation when a - screenshot is no longer needed or has been replaced by an updated image. + 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. - **Parameters** + Requires manage permission on the screenshot and the write scope on the access token. Returns 403 if the account plan does not include the screenshot feature or if the access token lacks the write scope. Returns 404 if the screenshot does not exist in the specified project. - | Name | In | Type | Required | Description | - |------|----|------|----------|-------------| - | X-PhraseApp-OTP | header | string | No | Two-factor authentication token. OTP (One-Time Password) value from your authenticator app, required only when 2FA is enabled on the account. | - | project_id | path | string | Yes | Unique string code identifying the project (for example, `3d7ce831a3e9e1b843dc16d36ee5b9f4`). | - | id | path | string | Yes | String code of the screenshot to delete (for example, `d2e056aa9e70b01121f41693e344f5ee`). This is the `id` field returned by the create, show, and list screenshot endpoints — it is not a numeric primary key. | - | branch | query | string | No | Name of the branch to use. When omitted the operation applies to the main project. | + Errors: - **Authorization:** Requires the `write` OAuth scope. The authenticated user - must have Manage permission on the Screenshot resource within the project. - - **Feature gate:** This endpoint is available only to accounts with the - Attachable Screenshots feature enabled. Requests from accounts on plans that - do not include this feature receive a 403 response with error code - `features_unavailable`. Requests originating from the Phrase Sketch Plugin - are additionally gated on the Sketch Plugin feature; accounts without that - feature also receive 403. - - **Cascade effect:** A successful deletion dispatches a `screenshots:delete` - event, which may trigger any configured webhook subscriptions for the project. - - **Validation failures (422):** If the underlying model destroy fails, the - response body contains a `message` string and an `errors` array with - per-field detail. Each entry in `errors` carries `resource`, `field`, and - `message`. - - **Errors** - - | Status | Error code | Cause | Resolution | - |--------|------------|-------|------------| - | 400 | `bad_request` | Malformed request parameters (for example, a branch name referencing a non-interactable branch). | Correct the request parameters and retry. | - | 401 | `unauthorized` | Authentication credentials are missing or invalid. | Supply a valid access token via `-u USERNAME:ACCESS_TOKEN` or the `Authorization` header. | - | 403 | `forbidden` | The access token lacks the `write` OAuth scope; the user account is unconfirmed; the authenticated user lacks Manage permission on the Screenshot resource; or the account does not have the Attachable Screenshots or Sketch Plugin feature enabled. | Use a token with the `write` scope, confirm the user account, or upgrade the subscription plan to one that includes Attachable Screenshots. | - | 404 | `not_found` | No screenshot with the given `id` exists in the specified project, or the `project_id` does not match any accessible project. | Verify both `project_id` and `id` using the list or show endpoints. | - | 422 | `unprocessable_entity` | The screenshot record could not be destroyed due to a model validation or database constraint failure. | Inspect the `errors` array in the response body for field-level detail. | - | 429 | `rate_limit_exceeded` | The request rate or concurrency limit for the access token has been exceeded. | Back off and retry after the interval indicated in the `X-Rate-Limit-Reset` response header. | -operationId: screenshots/delete + - screenshot_invalid_request (400): The request was malformed or a path parameter failed validation. Correct the parameter format and retry. + - screenshot_unauthorized (401): The access token is missing or invalid. Supply a valid access token. + - screenshot_forbidden (403): The access token lacks the write scope, the account plan does not include the screenshot feature, or the requesting user does not have manage permission on the screenshot. Upgrade your plan, add the write scope to your token, or request manage access. + - screenshot_not_found (404): No screenshot with this identifier exists in the project. Verify the project_id and id values. + - screenshot_unprocessable (422): The screenshot could not be deleted because the model reported validation errors. Inspect the errors array in the response body. + - screenshot_rate_limited (429): Too many requests have been made. Wait until the X-Rate-Limit-Reset time before retrying. +operationId: screenshot/delete tags: - Screenshots parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - name: X-PhraseApp-OTP - in: header - required: false - description: >- - OTP (One-Time Password) token from your authenticator app. Required only - when two-factor authentication is enabled on the account. - schema: - type: string - "$ref": "../../parameters.yaml#/project_id" - name: project_id - in: path - required: true - description: >- - Unique string code of the project (for example, - `3d7ce831a3e9e1b843dc16d36ee5b9f4`). - schema: - type: string - "$ref": "../../parameters.yaml#/id" - name: id - in: path - required: true - description: >- - String code of the screenshot to delete (for example, - `d2e056aa9e70b01121f41693e344f5ee`). This is the `id` field returned by - the create, show, and list screenshot endpoints. - schema: - type: string - pattern: '^[0-9a-f]{32}$' -- "$ref": "../../parameters.yaml#/branch" +- description: specify the branch to use + example: my-feature-branch name: branch in: query - required: false - description: >- - Name of the branch to use. When omitted the operation applies to the main - project. schema: type: string responses: '204': - description: >- - The screenshot was deleted successfully. No response body is returned. - The HTTP status `204 No Content` confirms deletion. - headers: - X-Rate-Limit-Limit: - "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" - X-Rate-Limit-Remaining: - "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" - X-Rate-Limit-Reset: - "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + "$ref": "../../responses.yaml#/204" + description: The screenshot and all its markers were deleted successfully. '400': "$ref": "../../responses.yaml#/400" - description: >- - Bad request. Returned when request parameters are malformed (for example, - referencing a non-interactable branch). Correct the request parameters - and retry. Error code: `bad_request`. + description: "screenshot_invalid_request: The request was malformed or a path parameter failed validation." '401': "$ref": "../../responses.yaml#/401" - description: >- - Unauthorized. Authentication credentials are missing or invalid. Supply a - valid access token. Error code: `unauthorized`. + 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` OAuth scope; - the user account is unconfirmed; the authenticated user lacks Manage - permission on the Screenshot resource in this project; or the account - subscription does not include the Attachable Screenshots or Sketch Plugin - feature. To resolve: use a token with the `write` scope, confirm the user - account, or upgrade to a plan that includes Attachable Screenshots. - Error code: `forbidden` or `features_unavailable`. + 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: >- - Not found. No screenshot with the given `id` exists in the specified - project, or the `project_id` is invalid. Verify both identifiers using - the list or show endpoints. Error code: `not_found`. + description: "screenshot_not_found: No screenshot with this identifier exists in the specified project." '422': "$ref": "../../responses.yaml#/422" - description: >- - Unprocessable entity. The screenshot record could not be destroyed due to - a model validation or constraint failure. Inspect the `errors` array in - the response body for field-level detail. Error code: - `unprocessable_entity`. + 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: >- - Too many requests. The request rate or concurrency limit has been - exceeded. Back off and retry after the interval indicated in the - `X-Rate-Limit-Reset` response header. Error code: `rate_limit_exceeded`. + 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/3d7ce831a3e9e1b843dc16d36ee5b9f4/screenshots/d2e056aa9e70b01121f41693e344f5ee" \ - -u stephenlumenta:AbCdEf123456789xYzAbCdEf123456789xYz \ + curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ + -u USERNAME_OR_ACCESS_TOKEN \ -X DELETE - # Expected response: HTTP 204 No Content (empty body) + + HTTP/1.1 204 No Content - lang: CLI v2 source: |- phrase screenshots delete \ - --project_id 3d7ce831a3e9e1b843dc16d36ee5b9f4 \ - --id d2e056aa9e70b01121f41693e344f5ee \ - --branch my-feature-branch \ - --access_token AbCdEf123456789xYzAbCdEf123456789xYz - # Expected response: HTTP 204 No Content (empty body) + --project_id \ + --id \ + --access_token x-cli-version: '2.5' +security: + - Token: [] + - OAuth2: + - write From 60d00e850c06c950ad429659bfd03da4d9897922 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 20:55:18 +0100 Subject: [PATCH 3/3] docs(API): address review on delete /projects/{project_id}/screenshots/{id} - Remove the per-status 'Errors:' enumeration from the top-level description; each status code already carries its own description on the response object (theSoenke). - Drop the 'HTTP/1.1 204 No Content' response line from the curl sample so it shows only the request, like every other endpoint. - Remove the endpoint-level security block. No other endpoint declares one; global security (Token/Basic) already applies, and the block was silently swapping Basic for OAuth2 on just this operation. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 16 +++------------- paths/screenshots/destroy.yaml | 17 ----------------- 2 files changed, 3 insertions(+), 30 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 64270ec5..00a06e55 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21421,7 +21421,7 @@ }, "delete": { "summary": "Delete a 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\nRequires manage permission on the screenshot and the write scope on the access token. Returns 403 if the account plan does not include the screenshot feature or if the access token lacks the write scope. Returns 404 if the screenshot does not exist in the specified project.\n\nErrors:\n\n- screenshot_invalid_request (400): The request was malformed or a path parameter failed validation. Correct the parameter format and retry.\n- screenshot_unauthorized (401): The access token is missing or invalid. Supply a valid access token.\n- screenshot_forbidden (403): The access token lacks the write scope, the account plan does not include the screenshot feature, or the requesting user does not have manage permission on the screenshot. Upgrade your plan, add the write scope to your token, or request manage access.\n- screenshot_not_found (404): No screenshot with this identifier exists in the project. Verify the project_id and id values.\n- screenshot_unprocessable (422): The screenshot could not be deleted because the model reported validation errors. Inspect the errors array in the response body.\n- screenshot_rate_limited (429): Too many requests have been made. Wait until the X-Rate-Limit-Reset time before retrying.\n", + "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" @@ -21479,24 +21479,14 @@ "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\nHTTP/1.1 204 No Content" + "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 --access_token " } ], - "x-cli-version": "2.5", - "security": [ - { - "Token": [] - }, - { - "OAuth2": [ - "write" - ] - } - ] + "x-cli-version": "2.5" } }, "/accounts/{account_id}/glossaries/{glossary_id}/terms": { diff --git a/paths/screenshots/destroy.yaml b/paths/screenshots/destroy.yaml index 50d3312a..bd33e6c6 100644 --- a/paths/screenshots/destroy.yaml +++ b/paths/screenshots/destroy.yaml @@ -2,17 +2,6 @@ summary: Delete a 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. - - Requires manage permission on the screenshot and the write scope on the access token. Returns 403 if the account plan does not include the screenshot feature or if the access token lacks the write scope. Returns 404 if the screenshot does not exist in the specified project. - - Errors: - - - screenshot_invalid_request (400): The request was malformed or a path parameter failed validation. Correct the parameter format and retry. - - screenshot_unauthorized (401): The access token is missing or invalid. Supply a valid access token. - - screenshot_forbidden (403): The access token lacks the write scope, the account plan does not include the screenshot feature, or the requesting user does not have manage permission on the screenshot. Upgrade your plan, add the write scope to your token, or request manage access. - - screenshot_not_found (404): No screenshot with this identifier exists in the project. Verify the project_id and id values. - - screenshot_unprocessable (422): The screenshot could not be deleted because the model reported validation errors. Inspect the errors array in the response body. - - screenshot_rate_limited (429): Too many requests have been made. Wait until the X-Rate-Limit-Reset time before retrying. operationId: screenshot/delete tags: - Screenshots @@ -54,8 +43,6 @@ x-code-samples: curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ -u USERNAME_OR_ACCESS_TOKEN \ -X DELETE - - HTTP/1.1 204 No Content - lang: CLI v2 source: |- phrase screenshots delete \ @@ -63,7 +50,3 @@ x-code-samples: --id \ --access_token x-cli-version: '2.5' -security: - - Token: [] - - OAuth2: - - write