From 43917b4ef111e03e2cf74ac263ce5d4d749e76e2 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:57:31 +0200 Subject: [PATCH 1/5] 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/5] 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: |- From 8b1f377fd18d15ad5666af25890251f420fa248b Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:07:03 +0200 Subject: [PATCH 3/5] 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 | 15 +++++---------- paths/screenshots/show.yaml | 5 ----- 2 files changed, 5 insertions(+), 15 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 908c2641..e4c4e7c2 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21286,24 +21286,19 @@ } }, "400": { - "$ref": "#/components/responses/400", - "description": "BAD_REQUEST: malformed request parameters." + "$ref": "#/components/responses/400" }, "401": { - "$ref": "#/components/responses/401", - "description": "UNAUTHORIZED: missing or invalid access token." + "$ref": "#/components/responses/401" }, "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." + "$ref": "#/components/responses/403" }, "404": { - "$ref": "#/components/responses/404", - "description": "NOT_FOUND: the project or screenshot does not exist under the given identifiers." + "$ref": "#/components/responses/404" }, "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." + "$ref": "#/components/responses/429" } }, "x-code-samples": [ diff --git a/paths/screenshots/show.yaml b/paths/screenshots/show.yaml index 0ae9ce90..96c34f46 100644 --- a/paths/screenshots/show.yaml +++ b/paths/screenshots/show.yaml @@ -34,19 +34,14 @@ 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: |- From b5da146493f079ea004ef0381009aaf6446b8b31 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 10:29:18 +0200 Subject: [PATCH 4/5] 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/screenshots/show.yaml | 11 ----------- 2 files changed, 21 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index e4c4e7c2..18653fbf 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21301,16 +21301,6 @@ "$ref": "#/components/responses/429" } }, - "x-code-samples": [ - { - "lang": "Curl", - "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--access_token " - } - ], "x-cli-version": "2.5" }, "patch": { diff --git a/paths/screenshots/show.yaml b/paths/screenshots/show.yaml index 96c34f46..712888ed 100644 --- a/paths/screenshots/show.yaml +++ b/paths/screenshots/show.yaml @@ -42,15 +42,4 @@ responses: "$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" \ - -u USERNAME_OR_ACCESS_TOKEN -- lang: CLI v2 - source: |- - phrase screenshots show \ - --project_id \ - --id \ - --access_token x-cli-version: '2.5' From cf582854d2355e831e64ab443e91b9c008c087a3 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 29 Jun 2026 21:24:07 +0200 Subject: [PATCH 5/5] fix(API): keep CLI v2 code sample, only drop hand-written Curl New strings rubric rule: Mintlify auto-generates the request curl, so a hand-written Curl sample is redundant and overrides it, but a CLI v2 sample cannot be derived from the spec and must be preserved. This PR originally removed the whole x-code-samples block; restore the CLI v2 entry (Curl stays dropped). compiled.json regenerated via make bundle. --- doc/compiled.json | 6 ++++++ paths/screenshots/show.yaml | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/doc/compiled.json b/doc/compiled.json index c5623cb9..af8b7416 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21586,6 +21586,12 @@ "$ref": "#/components/responses/429" } }, + "x-code-samples": [ + { + "lang": "CLI v2", + "source": "phrase screenshots show \\\n--project_id \\\n--id \\\n--branch my-feature-branch \\\n--access_token " + } + ], "x-cli-version": "2.5" }, "patch": { diff --git a/paths/screenshots/show.yaml b/paths/screenshots/show.yaml index 712888ed..fd6058d3 100644 --- a/paths/screenshots/show.yaml +++ b/paths/screenshots/show.yaml @@ -42,4 +42,12 @@ responses: "$ref": "../../responses.yaml#/404" '429': "$ref": "../../responses.yaml#/429" +x-code-samples: +- lang: CLI v2 + source: |- + phrase screenshots show \ + --project_id \ + --id \ + --branch my-feature-branch \ + --access_token x-cli-version: '2.5'