From a0f82af4588c8b7dcf3031d5465352191b6c9790 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:57:45 +0200 Subject: [PATCH 1/8] feat(API): improve patch /projects/{project_id}/screenshots/{id} documentation --- doc/compiled.json | 90 +++++++++++++++------------ paths/screenshots/update.yaml | 111 ++++++++++++++++++++++------------ 2 files changed, 125 insertions(+), 76 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..df6b218f 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21315,7 +21315,7 @@ }, "patch": { "summary": "Update a screenshot", - "description": "Update an existing screenshot.", + "description": "Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource.\n\nUse this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one.\n\nRequires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project.\n\nThe name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed.\n\n**Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying.\n", "operationId": "screenshot/update", "tags": [ "Screenshots" @@ -21331,6 +21331,42 @@ "$ref": "#/components/parameters/id" } ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "title": "screenshot/update/parameters", + "required": [], + "properties": { + "branch": { + "description": "Branch to use for the operation. Omit to update the screenshot on the default branch.", + "type": "string", + "example": "my-feature-branch" + }, + "name": { + "description": "New display name for the screenshot. Must be non-empty and unique within the project (case-insensitive). Omit to leave the current name unchanged.", + "type": "string", + "minLength": 1, + "example": "home_screen_v2" + }, + "description": { + "description": "Updated description for the screenshot. Omit to leave the current description unchanged.", + "type": "string", + "example": "Updated landing page screenshot" + }, + "filename": { + "description": "Screenshot file", + "type": "string", + "format": "binary", + "example": "/path/to/my/screenshot.png" + } + } + } + } + } + }, "responses": { "200": { "description": "OK", @@ -21338,6 +21374,15 @@ "application/json": { "schema": { "$ref": "#/components/schemas/screenshot" + }, + "example": { + "id": "d2e056aa9e70b01121f41693e344f5ee", + "name": "home_screen_v2", + "description": "Updated landing page screenshot", + "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + "created_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-06-14T09:15:00Z", + "markers_count": 3 } } }, @@ -21360,8 +21405,7 @@ "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to update this screenshot, or when the account does not have the Attachable Screenshots feature." + "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" @@ -21376,47 +21420,15 @@ "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 PATCH \\\n -F branch=my-feature-branch \\\n -F name=A%20screenshot%20name \\\n -F description=A%20screenshot%20description \\\n -F filename=@/path/to/my/screenshot.png" + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=home_screen_v2\" \\\n -F \"description=Updated landing page screenshot\"", + "response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}" }, { "lang": "CLI v2", - "source": "phrase screenshots update \\\n--project_id \\\n--id \\\n--data '{\"branch\":\"my-feature-branch\", \"name\": \"A screenshot name\", \"description\": \"A screenshot description\", \"filename\":\"/path/to/my/screenshot.png\"}' \\\n--access_token " + "source": "phrase screenshots update \\\n--project_id abcd1234abcd1234abcd1234abcd1234 \\\n--id d2e056aa9e70b01121f41693e344f5ee \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token YOUR_ACCESS_TOKEN", + "response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}" } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "title": "screenshot/update/parameters", - "properties": { - "branch": { - "description": "specify the branch to use", - "type": "string", - "example": "my-feature-branch" - }, - "name": { - "description": "Name of the screenshot", - "type": "string", - "example": "A screenshot name" - }, - "description": { - "description": "Description of the screenshot", - "type": "string", - "example": "A screenshot description" - }, - "filename": { - "description": "Screenshot file", - "type": "string", - "format": "binary", - "example": "/path/to/my/screenshot.png" - } - } - } - } - } - }, "x-cli-version": "2.5" }, "delete": { diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index df4f3e29..771ce090 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -1,6 +1,15 @@ --- summary: Update a screenshot -description: Update an existing screenshot. +description: | + Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource. + + Use this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one. + + Requires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project. + + The name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed. + + **Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying. operationId: screenshot/update tags: - Screenshots @@ -8,6 +17,33 @@ parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/id" +requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + title: screenshot/update/parameters + required: [] + properties: + branch: + description: Branch to use for the operation. Omit to update the screenshot on the default branch. + type: string + example: my-feature-branch + name: + description: New display name for the screenshot. Must be non-empty and unique within the project (case-insensitive). Omit to leave the current name unchanged. + type: string + minLength: 1 + example: home_screen_v2 + description: + description: Updated description for the screenshot. Omit to leave the current description unchanged. + type: string + example: Updated landing page screenshot + filename: + description: Screenshot file + type: string + format: binary + example: "/path/to/my/screenshot.png" responses: '200': description: OK @@ -15,6 +51,14 @@ responses: application/json: schema: "$ref": "../../schemas/screenshot.yaml#/screenshot" + example: + id: d2e056aa9e70b01121f41693e344f5ee + name: home_screen_v2 + description: Updated landing page screenshot + screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png + created_at: '2024-01-15T10:30:00Z' + updated_at: '2024-06-14T09:15:00Z' + markers_count: 3 headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -24,13 +68,12 @@ 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 `write` scope, when the requesting user is not allowed to update this screenshot, or when the account does not have the Attachable Screenshots feature. + '404': + "$ref": "../../responses.yaml#/404" '422': "$ref": "../../responses.yaml#/422" '429': @@ -41,40 +84,34 @@ x-code-samples: curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ -u USERNAME_OR_ACCESS_TOKEN \ -X PATCH \ - -F branch=my-feature-branch \ - -F name=A%20screenshot%20name \ - -F description=A%20screenshot%20description \ - -F filename=@/path/to/my/screenshot.png + -F "branch=my-feature-branch" \ + -F "name=home_screen_v2" \ + -F "description=Updated landing page screenshot" + response: |- + { + "id": "d2e056aa9e70b01121f41693e344f5ee", + "name": "home_screen_v2", + "description": "Updated landing page screenshot", + "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + "created_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-06-14T09:15:00Z", + "markers_count": 3 + } - lang: CLI v2 source: |- phrase screenshots update \ - --project_id \ - --id \ - --data '{"branch":"my-feature-branch", "name": "A screenshot name", "description": "A screenshot description", "filename":"/path/to/my/screenshot.png"}' \ - --access_token -requestBody: - required: true - content: - application/json: - schema: - type: object - title: screenshot/update/parameters - properties: - branch: - description: specify the branch to use - type: string - example: my-feature-branch - name: - description: Name of the screenshot - type: string - example: A screenshot name - description: - description: Description of the screenshot - type: string - example: A screenshot description - filename: - description: Screenshot file - type: string - format: binary - example: "/path/to/my/screenshot.png" + --project_id abcd1234abcd1234abcd1234abcd1234 \ + --id d2e056aa9e70b01121f41693e344f5ee \ + --data '{"branch":"my-feature-branch","name":"home_screen_v2","description":"Updated landing page screenshot"}' \ + --access_token YOUR_ACCESS_TOKEN + response: |- + { + "id": "d2e056aa9e70b01121f41693e344f5ee", + "name": "home_screen_v2", + "description": "Updated landing page screenshot", + "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + "created_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-06-14T09:15:00Z", + "markers_count": 3 + } x-cli-version: '2.5' From 40a530f6de94bc4b28388da7b4ab7427dce7f2e8 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:12:03 +0100 Subject: [PATCH 2/8] fix(API): clean up patch /projects/{project_id}/screenshots/{id} Apply the batch review conventions: - Move the per-status 'Errors:' prose and the scope/permission sentence out of the top-level description and onto the response objects. - Remove the non-standard 'response:' block from each code sample; samples now show only the request, and the 200 example documents the response. - CLI sample: use // placeholders instead of concrete slug-like values. - Normalize the branch property to 'specify the branch to use'. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 28 +++++++++++++----------- paths/screenshots/update.yaml | 40 ++++++++++------------------------- 2 files changed, 27 insertions(+), 41 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index df6b218f..8333a7fb 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21315,7 +21315,7 @@ }, "patch": { "summary": "Update a screenshot", - "description": "Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource.\n\nUse this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one.\n\nRequires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project.\n\nThe name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed.\n\n**Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying.\n", + "description": "Updates the name or description of an existing screenshot. This endpoint follows the standard REST resource-update lifecycle: send only the fields you want to change and the server applies them to the existing resource.\n\nUse this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one.\n\nThe name must be unique within the project (case-insensitive). Existing screenshot markers are unaffected unless marker attributes are explicitly passed.\n", "operationId": "screenshot/update", "tags": [ "Screenshots" @@ -21341,7 +21341,7 @@ "required": [], "properties": { "branch": { - "description": "Branch to use for the operation. Omit to update the screenshot on the default branch.", + "description": "specify the branch to use", "type": "string", "example": "my-feature-branch" }, @@ -21399,34 +21399,38 @@ } }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "Returned for malformed request parameters; verify parameter names and value types." }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "Returned when no valid access token is supplied." }, "403": { - "$ref": "#/components/responses/403" + "$ref": "#/components/responses/403", + "description": "Returned when the Screenshots feature is not enabled on the account or the token lacks the write scope." }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "Returned when no screenshot with the given id exists in the project." }, "422": { - "$ref": "#/components/responses/422" + "$ref": "#/components/responses/422", + "description": "Returned when validation fails, most commonly because the name is blank or already used by another screenshot in the project." }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "Returned when the rate limit is exceeded. Wait for the interval indicated in the X-Rate-Limit-Reset response header 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 PATCH \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=home_screen_v2\" \\\n -F \"description=Updated landing page screenshot\"", - "response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}" + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=home_screen_v2\" \\\n -F \"description=Updated landing page screenshot\"" }, { "lang": "CLI v2", - "source": "phrase screenshots update \\\n--project_id abcd1234abcd1234abcd1234abcd1234 \\\n--id d2e056aa9e70b01121f41693e344f5ee \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token YOUR_ACCESS_TOKEN", - "response": "{\n \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n \"name\": \"home_screen_v2\",\n \"description\": \"Updated landing page screenshot\",\n \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n \"created_at\": \"2024-01-15T10:30:00Z\",\n \"updated_at\": \"2024-06-14T09:15:00Z\",\n \"markers_count\": 3\n}" + "source": "phrase screenshots update \\\n--project_id \\\n--id \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token " } ], "x-cli-version": "2.5" diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index 771ce090..40ee9b54 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -5,11 +5,7 @@ description: | Use this when you need to rename a screenshot or revise its contextual description without replacing the image file. Updating screenshot markers is also possible through this endpoint by passing marker attributes. The image file itself cannot be changed; to replace it, delete the screenshot and create a new one. - Requires the Screenshots feature to be enabled on the account and the write scope on the access token. The caller must have manage permission on the project. - - The name must be unique within the project (case-insensitive). Submitting a blank name returns 422. Existing screenshot markers are unaffected unless marker attributes are explicitly passed. - - **Errors:** Returns 400 for malformed request parameters — verify parameter names and value types. Returns 401 when no valid access token is supplied — include a valid token and retry. Returns 403 when the Screenshots feature is not enabled on the account or the token lacks the write scope — upgrade the account plan or regenerate the token with the correct scope. Returns 404 when no screenshot with the given id exists in the project — confirm the id is correct for this project. Returns 422 when validation fails, most commonly because the name is blank or already used by another screenshot in the project — choose a non-empty, unique name. Returns 429 when the rate limit is exceeded — wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying. + The name must be unique within the project (case-insensitive). Existing screenshot markers are unaffected unless marker attributes are explicitly passed. operationId: screenshot/update tags: - Screenshots @@ -27,7 +23,7 @@ requestBody: required: [] properties: branch: - description: Branch to use for the operation. Omit to update the screenshot on the default branch. + description: specify the branch to use type: string example: my-feature-branch name: @@ -68,16 +64,22 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" + description: Returned for malformed request parameters; verify parameter names and value types. '401': "$ref": "../../responses.yaml#/401" + description: Returned when no valid access token is supplied. '403': "$ref": "../../responses.yaml#/403" + description: Returned when the Screenshots feature is not enabled on the account or the token lacks the write scope. '404': "$ref": "../../responses.yaml#/404" + description: Returned when no screenshot with the given id exists in the project. '422': "$ref": "../../responses.yaml#/422" + description: Returned when validation fails, most commonly because the name is blank or already used by another screenshot in the project. '429': "$ref": "../../responses.yaml#/429" + description: Returned when the rate limit is exceeded. Wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying. x-code-samples: - lang: Curl source: |- @@ -87,31 +89,11 @@ x-code-samples: -F "branch=my-feature-branch" \ -F "name=home_screen_v2" \ -F "description=Updated landing page screenshot" - response: |- - { - "id": "d2e056aa9e70b01121f41693e344f5ee", - "name": "home_screen_v2", - "description": "Updated landing page screenshot", - "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", - "created_at": "2024-01-15T10:30:00Z", - "updated_at": "2024-06-14T09:15:00Z", - "markers_count": 3 - } - lang: CLI v2 source: |- phrase screenshots update \ - --project_id abcd1234abcd1234abcd1234abcd1234 \ - --id d2e056aa9e70b01121f41693e344f5ee \ + --project_id \ + --id \ --data '{"branch":"my-feature-branch","name":"home_screen_v2","description":"Updated landing page screenshot"}' \ - --access_token YOUR_ACCESS_TOKEN - response: |- - { - "id": "d2e056aa9e70b01121f41693e344f5ee", - "name": "home_screen_v2", - "description": "Updated landing page screenshot", - "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", - "created_at": "2024-01-15T10:30:00Z", - "updated_at": "2024-06-14T09:15:00Z", - "markers_count": 3 - } + --access_token x-cli-version: '2.5' From d941729aa6c97ef02648c0fea8f952bde29e0d7a Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:13:25 +0100 Subject: [PATCH 3/8] fix(API): drop invalid empty 'required: []' on screenshot update body An empty 'required' array is invalid under the OpenAPI 3.0 meta-schema (it must have at least one entry), which was failing 'swagger-cli validate' in the lint gate. The endpoint has no required fields, so the key is simply removed. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 1 - paths/screenshots/update.yaml | 1 - 2 files changed, 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 8333a7fb..7f84e7eb 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21338,7 +21338,6 @@ "schema": { "type": "object", "title": "screenshot/update/parameters", - "required": [], "properties": { "branch": { "description": "specify the branch to use", diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index 40ee9b54..f62b0cc7 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -20,7 +20,6 @@ requestBody: schema: type: object title: screenshot/update/parameters - required: [] properties: branch: description: specify the branch to use From c1de3278716f9093db636cff9573fc41b7363a3e Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:07:07 +0200 Subject: [PATCH 4/8] 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 | 18 ++++++------------ paths/screenshots/update.yaml | 6 ------ 2 files changed, 6 insertions(+), 18 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 7f84e7eb..7fa77166 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21398,28 +21398,22 @@ } }, "400": { - "$ref": "#/components/responses/400", - "description": "Returned for malformed request parameters; verify parameter names and value types." + "$ref": "#/components/responses/400" }, "401": { - "$ref": "#/components/responses/401", - "description": "Returned when no valid access token is supplied." + "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Returned when the Screenshots feature is not enabled on the account or the token lacks the write scope." + "$ref": "#/components/responses/403" }, "404": { - "$ref": "#/components/responses/404", - "description": "Returned when no screenshot with the given id exists in the project." + "$ref": "#/components/responses/404" }, "422": { - "$ref": "#/components/responses/422", - "description": "Returned when validation fails, most commonly because the name is blank or already used by another screenshot in the project." + "$ref": "#/components/responses/422" }, "429": { - "$ref": "#/components/responses/429", - "description": "Returned when the rate limit is exceeded. Wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying." + "$ref": "#/components/responses/429" } }, "x-code-samples": [ diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index f62b0cc7..09dc8621 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -63,22 +63,16 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" - description: Returned for malformed request parameters; verify parameter names and value types. '401': "$ref": "../../responses.yaml#/401" - description: Returned when no valid access token is supplied. '403': "$ref": "../../responses.yaml#/403" - description: Returned when the Screenshots feature is not enabled on the account or the token lacks the write scope. '404': "$ref": "../../responses.yaml#/404" - description: Returned when no screenshot with the given id exists in the project. '422': "$ref": "../../responses.yaml#/422" - description: Returned when validation fails, most commonly because the name is blank or already used by another screenshot in the project. '429': "$ref": "../../responses.yaml#/429" - description: Returned when the rate limit is exceeded. Wait for the interval indicated in the X-Rate-Limit-Reset response header before retrying. x-code-samples: - lang: Curl source: |- From 12f75f6fa480ed087ffbb53bb77dbcf5d52e0e18 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 10:29:30 +0200 Subject: [PATCH 5/8] 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/update.yaml | 16 ---------------- 2 files changed, 26 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 7fa77166..338b2cd8 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21416,16 +21416,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 \\\n -X PATCH \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=home_screen_v2\" \\\n -F \"description=Updated landing page screenshot\"" - }, - { - "lang": "CLI v2", - "source": "phrase screenshots update \\\n--project_id \\\n--id \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token " - } - ], "x-cli-version": "2.5" }, "delete": { diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index 09dc8621..bddd1b17 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -73,20 +73,4 @@ responses: "$ref": "../../responses.yaml#/422" '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 \ - -X PATCH \ - -F "branch=my-feature-branch" \ - -F "name=home_screen_v2" \ - -F "description=Updated landing page screenshot" -- lang: CLI v2 - source: |- - phrase screenshots update \ - --project_id \ - --id \ - --data '{"branch":"my-feature-branch","name":"home_screen_v2","description":"Updated landing page screenshot"}' \ - --access_token x-cli-version: '2.5' From ad2d7ad14f3f93a405c897b6faec77966acbd263 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Thu, 25 Jun 2026 13:30:18 +0200 Subject: [PATCH 6/8] fix(API): drop redundant inline example on screenshot update response The 200 response already references `schemas/screenshot.yaml#/screenshot`, which carries a schema-level example covering every field. The inline example here just duplicated it (and drifts from the canonical one the show endpoint renders). Remove it so update and show render the same shared example. Co-Authored-By: Claude Opus 4.8 (1M context) --- paths/screenshots/update.yaml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index bddd1b17..89a78efe 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -46,14 +46,6 @@ responses: application/json: schema: "$ref": "../../schemas/screenshot.yaml#/screenshot" - example: - id: d2e056aa9e70b01121f41693e344f5ee - name: home_screen_v2 - description: Updated landing page screenshot - screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png - created_at: '2024-01-15T10:30:00Z' - updated_at: '2024-06-14T09:15:00Z' - markers_count: 3 headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" From 719d3482ea56a2b2eb998f9d42c9f944b09b8735 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Thu, 25 Jun 2026 13:42:31 +0200 Subject: [PATCH 7/8] chore(spec): rebundle doc/compiled.json after the schema dedup edits Regenerated from source with `swagger-cli bundle -t json -w 300 main.yaml` (the exact command the lint/compare-output CI job runs), so the committed bundle matches a fresh bundle of the deduped YAML. Fixes the compare-output failure introduced by editing the source without rebundling. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 9 --------- 1 file changed, 9 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 67dd3e88..f2846bb2 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21658,15 +21658,6 @@ "application/json": { "schema": { "$ref": "#/components/schemas/screenshot" - }, - "example": { - "id": "d2e056aa9e70b01121f41693e344f5ee", - "name": "home_screen_v2", - "description": "Updated landing page screenshot", - "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", - "created_at": "2024-01-15T10:30:00Z", - "updated_at": "2024-06-14T09:15:00Z", - "markers_count": 3 } } }, From f86cdd8ad69884ef4190f302d41a3659b530c59e Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 29 Jun 2026 21:24:11 +0200 Subject: [PATCH 8/8] 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/update.yaml | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/doc/compiled.json b/doc/compiled.json index f2846bb2..09ec6444 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21616,6 +21616,12 @@ "$ref": "#/components/parameters/id" } ], + "x-code-samples": [ + { + "lang": "CLI v2", + "source": "phrase screenshots update \\\n--project_id \\\n--id \\\n--data '{\"branch\":\"my-feature-branch\", \"name\": \"A screenshot name\", \"description\": \"A screenshot description\", \"filename\":\"/path/to/my/screenshot.png\"}' \\\n--access_token " + } + ], "requestBody": { "required": true, "content": { diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index 89a78efe..77be8c20 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -13,6 +13,14 @@ parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" - "$ref": "../../parameters.yaml#/project_id" - "$ref": "../../parameters.yaml#/id" +x-code-samples: +- lang: CLI v2 + source: |- + phrase screenshots update \ + --project_id \ + --id \ + --data '{"branch":"my-feature-branch", "name": "A screenshot name", "description": "A screenshot description", "filename":"/path/to/my/screenshot.png"}' \ + --access_token requestBody: required: true content: