From 43917b4ef111e03e2cf74ac263ce5d4d749e76e2 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:57:31 +0200 Subject: [PATCH 1/2] feat(API): improve get /projects/{project_id}/screenshots/{id} documentation --- doc/compiled.json | 12 ++++++------ paths/screenshots/show.yaml | 26 +++++++++++++++++++------- 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..185d2bed 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21237,7 +21237,7 @@ "/projects/{project_id}/screenshots/{id}": { "get": { "summary": "Get a single screenshot", - "description": "Get details on a single screenshot for a given project.", + "description": "Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects.\n\nThe Attachable Screenshots feature must be enabled on the account. Users with project read access can retrieve any screenshot in that project.\n\n**Error reference**\n\n| HTTP status | Code | Cause | Remediation |\n|---|---|---|---|\n| 400 | BAD_REQUEST | Malformed request parameters | Check query parameter syntax and types |\n| 401 | UNAUTHORIZED | Missing or invalid access token | Provide a valid access token via the Authorization header or access_token query parameter |\n| 403 | FORBIDDEN | Access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account | Verify scope, project membership, and account feature availability |\n| 404 | NOT_FOUND | The project or screenshot does not exist under the given identifiers | Confirm the project_id and screenshot id are correct |\n| 429 | RATE_LIMIT_EXCEEDED | Too many requests in the current window | Wait for the reset time indicated by X-Rate-Limit-Reset before retrying |\n", "operationId": "screenshot/show", "tags": [ "Screenshots" @@ -21253,10 +21253,11 @@ "$ref": "#/components/parameters/id" }, { - "description": "specify the branch to use", + "description": "Name of the branch to read the screenshot from. Defaults to the project default branch when omitted.", "example": "my-feature-branch", "name": "branch", "in": "query", + "required": false, "schema": { "type": "string" } @@ -21291,8 +21292,7 @@ "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this screenshot, or when the account does not have the Attachable Screenshots feature." + "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" @@ -21304,11 +21304,11 @@ "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN" }, { "lang": "CLI v2", - "source": "phrase screenshots show \\\n--project_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " + "source": "phrase screenshots show \\\n--project_id \\\n--id \\\n--access_token " } ], "x-cli-version": "2.5" diff --git a/paths/screenshots/show.yaml b/paths/screenshots/show.yaml index ad73d271..2ec0cf78 100644 --- a/paths/screenshots/show.yaml +++ b/paths/screenshots/show.yaml @@ -1,6 +1,19 @@ --- summary: Get a single screenshot -description: Get details on a single screenshot for a given project. +description: | + Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects. + + The Attachable Screenshots feature must be enabled on the account. Users with project read access can retrieve any screenshot in that project. + + **Error reference** + + | HTTP status | Code | Cause | Remediation | + |---|---|---|---| + | 400 | BAD_REQUEST | Malformed request parameters | Check query parameter syntax and types | + | 401 | UNAUTHORIZED | Missing or invalid access token | Provide a valid access token via the Authorization header or access_token query parameter | + | 403 | FORBIDDEN | Access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account | Verify scope, project membership, and account feature availability | + | 404 | NOT_FOUND | The project or screenshot does not exist under the given identifiers | Confirm the project_id and screenshot id are correct | + | 429 | RATE_LIMIT_EXCEEDED | Too many requests in the current window | Wait for the reset time indicated by X-Rate-Limit-Reset before retrying | operationId: screenshot/show tags: - Screenshots @@ -8,10 +21,11 @@ parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/id" -- description: specify the branch to use +- description: Name of the branch to read the screenshot from. Defaults to the project default branch when omitted. example: my-feature-branch name: branch in: query + required: false schema: type: string responses: @@ -30,25 +44,23 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" '401': "$ref": "../../responses.yaml#/401" '403': "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this screenshot, or when the account does not have the Attachable Screenshots feature. + '404': + "$ref": "../../responses.yaml#/404" '429': "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl source: |- - curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch" \ + curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ -u USERNAME_OR_ACCESS_TOKEN - lang: CLI v2 source: |- phrase screenshots show \ --project_id \ --id \ - --branch my-feature-branch \ --access_token x-cli-version: '2.5' From a738307dc76615f14a928e580c546e4cffc6730a Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:14:48 +0100 Subject: [PATCH 2/2] docs(API): clean up get /projects/{project_id}/screenshots/{id} Apply the batch review conventions: - Move the 'Error reference' table out of the top-level description and onto the response objects (400/401/403/404/429 carry their own description); keep only purpose and the feature-availability note. - Normalize the branch parameter to 'specify the branch to use'. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 19 ++++++++++++------- paths/screenshots/show.yaml | 19 +++++++------------ 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 185d2bed..908c2641 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21237,7 +21237,7 @@ "/projects/{project_id}/screenshots/{id}": { "get": { "summary": "Get a single screenshot", - "description": "Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects.\n\nThe Attachable Screenshots feature must be enabled on the account. Users with project read access can retrieve any screenshot in that project.\n\n**Error reference**\n\n| HTTP status | Code | Cause | Remediation |\n|---|---|---|---|\n| 400 | BAD_REQUEST | Malformed request parameters | Check query parameter syntax and types |\n| 401 | UNAUTHORIZED | Missing or invalid access token | Provide a valid access token via the Authorization header or access_token query parameter |\n| 403 | FORBIDDEN | Access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account | Verify scope, project membership, and account feature availability |\n| 404 | NOT_FOUND | The project or screenshot does not exist under the given identifiers | Confirm the project_id and screenshot id are correct |\n| 429 | RATE_LIMIT_EXCEEDED | Too many requests in the current window | Wait for the reset time indicated by X-Rate-Limit-Reset before retrying |\n", + "description": "Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects.\n\nThe Attachable Screenshots feature must be enabled on the account.\n", "operationId": "screenshot/show", "tags": [ "Screenshots" @@ -21253,7 +21253,7 @@ "$ref": "#/components/parameters/id" }, { - "description": "Name of the branch to read the screenshot from. Defaults to the project default branch when omitted.", + "description": "specify the branch to use", "example": "my-feature-branch", "name": "branch", "in": "query", @@ -21286,19 +21286,24 @@ } }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "BAD_REQUEST: malformed request parameters." }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "UNAUTHORIZED: missing or invalid access token." }, "403": { - "$ref": "#/components/responses/403" + "$ref": "#/components/responses/403", + "description": "FORBIDDEN: the access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account." }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "NOT_FOUND: the project or screenshot does not exist under the given identifiers." }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "RATE_LIMIT_EXCEEDED: too many requests. Wait for the reset time indicated by X-Rate-Limit-Reset before retrying." } }, "x-code-samples": [ diff --git a/paths/screenshots/show.yaml b/paths/screenshots/show.yaml index 2ec0cf78..0ae9ce90 100644 --- a/paths/screenshots/show.yaml +++ b/paths/screenshots/show.yaml @@ -3,17 +3,7 @@ summary: Get a single screenshot description: | Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects. - The Attachable Screenshots feature must be enabled on the account. Users with project read access can retrieve any screenshot in that project. - - **Error reference** - - | HTTP status | Code | Cause | Remediation | - |---|---|---|---| - | 400 | BAD_REQUEST | Malformed request parameters | Check query parameter syntax and types | - | 401 | UNAUTHORIZED | Missing or invalid access token | Provide a valid access token via the Authorization header or access_token query parameter | - | 403 | FORBIDDEN | Access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account | Verify scope, project membership, and account feature availability | - | 404 | NOT_FOUND | The project or screenshot does not exist under the given identifiers | Confirm the project_id and screenshot id are correct | - | 429 | RATE_LIMIT_EXCEEDED | Too many requests in the current window | Wait for the reset time indicated by X-Rate-Limit-Reset before retrying | + The Attachable Screenshots feature must be enabled on the account. operationId: screenshot/show tags: - Screenshots @@ -21,7 +11,7 @@ parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/id" -- description: Name of the branch to read the screenshot from. Defaults to the project default branch when omitted. +- description: specify the branch to use example: my-feature-branch name: branch in: query @@ -44,14 +34,19 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" + description: "BAD_REQUEST: malformed request parameters." '401': "$ref": "../../responses.yaml#/401" + description: "UNAUTHORIZED: missing or invalid access token." '403': "$ref": "../../responses.yaml#/403" + description: "FORBIDDEN: the access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account." '404': "$ref": "../../responses.yaml#/404" + description: "NOT_FOUND: the project or screenshot does not exist under the given identifiers." '429': "$ref": "../../responses.yaml#/429" + description: "RATE_LIMIT_EXCEEDED: too many requests. Wait for the reset time indicated by X-Rate-Limit-Reset before retrying." x-code-samples: - lang: Curl source: |-