Skip to content

fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation #1190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Stephen Lumenta (sbl) wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix(API): improve patch /projects/{project_id}/screenshots/{id} documentation #1190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a0f82af
feat(API): improve patch /projects/{project_id}/screenshots/{id} docu…
sbl Jun 15, 2026
40a530f
fix(API): clean up patch /projects/{project_id}/screenshots/{id}
sbl Jun 17, 2026
d941729
fix(API): drop invalid empty 'required: []' on screenshot update body
sbl Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 58 additions & 43 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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\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"
Expand All @@ -21331,13 +21331,57 @@
"$ref": "#/components/parameters/id"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"title": "screenshot/update/parameters",
"properties": {
"branch": {
"description": "specify the branch to use",
"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",
"content": {
"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
}
}
},
Expand All @@ -21354,69 +21398,40 @@
}
},
"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",
"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."
"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=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\""
},
{
"lang": "CLI v2",
"source": "phrase screenshots update \\\n--project_id <project_id> \\\n--id <id> \\\n--data '{\"branch\":\"my-feature-branch\", \"name\": \"A screenshot name\", \"description\": \"A screenshot description\", \"filename\":\"/path/to/my/screenshot.png\"}' \\\n--access_token <token>"
"source": "phrase screenshots update \\\n--project_id <project_id> \\\n--id <id> \\\n--data '{\"branch\":\"my-feature-branch\",\"name\":\"home_screen_v2\",\"description\":\"Updated landing page screenshot\"}' \\\n--access_token <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"
}
}
}
}
}
},
"x-cli-version": "2.5"
},
"delete": {
Expand Down
86 changes: 52 additions & 34 deletions paths/screenshots/update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,59 @@
---
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.

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
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
properties:
branch:
description: specify the branch to use
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
content:
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"
Expand All @@ -24,57 +63,36 @@ responses:
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
'400':
"$ref": "../../responses.yaml#/400"
'404':
"$ref": "../../responses.yaml#/404"
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: 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.
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: |-
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"
- lang: CLI v2
source: |-
phrase screenshots update \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "name": "A screenshot name", "description": "A screenshot description", "filename":"/path/to/my/screenshot.png"}' \
--data '{"branch":"my-feature-branch","name":"home_screen_v2","description":"Updated landing page screenshot"}' \
--access_token <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"
x-cli-version: '2.5'
Loading