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'