diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..3f6cad50 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 in a Phrase Strings project.\n\nUse this operation when you need to correct a screenshot's display name or clarify its description\nfor translators. Screenshots in Phrase Strings are images attached to translation keys to provide\nvisual context: they help translators understand where a string appears in the UI. Each screenshot\ncan have zero or more markers (`markers_count`) linking it to specific translation keys.\n\n**Important constraints and pitfalls:**\n- The `name` must be unique within the project (case-insensitive). Submitting a name that\n already exists on another screenshot in the same project returns a 422 error.\n- This endpoint does **not** accept a file upload. Replacing the image file (`filename`) is not\n supported via the update operation; to change the image, delete the screenshot and create a\n new one.\n- All body parameters are optional. Send only the fields you want to change; omitted fields are\n left unchanged.\n- The Attachable Screenshots feature must be enabled on the account. Requests from accounts\n without this feature receive a 403 response regardless of user permissions.\n- Only users with Manage permissions on the project may update screenshots. Users with only Read\n access receive a 403 response.\n\nOn success, a `screenshots:update` event is dispatched to configured webhooks.\n\n**Error codes:** Phrase Strings does not return stable machine-readable error code strings beyond\nthe HTTP status code. Use the HTTP status to branch error handling; read the `message` field in\nthe response body for a human-readable explanation.\n\n| HTTP status | Condition |\n|-------------|-----------|\n| 400 | Malformed request body (unparseable JSON) or a parameter value is of an unexpected type. |\n| 401 | Missing or invalid authentication credentials, or invalid OTP code. |\n| 403 | Token lacks the `write` scope; caller lacks manage permission; or account plan does not include the Screenshots feature. |\n| 404 | The project or screenshot does not exist or is not accessible to the caller. |\n| 422 | Screenshot attributes failed model validation (for example, a blank or duplicate name). |\n| 429 | The caller has exceeded their per-minute request quota or concurrent-request limit. |\n", "operationId": "screenshot/update", "tags": [ "Screenshots" @@ -21331,16 +21331,38 @@ "$ref": "#/components/parameters/id" } ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/screenshot" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "screenshot/update/parameters", + "description": "All properties are optional. Include only the fields you want to update.", + "properties": { + "branch": { + "description": "Name of the branch to operate on. When supplied, the request is scoped to that branch project rather than the main project. Omit to operate on the main project.", + "type": "string", + "example": "my-feature-branch" + }, + "name": { + "description": "New display name for the screenshot. Must be unique within the project (case-insensitive). If another screenshot in the project already uses this name, the request fails with 422.", + "type": "string", + "example": "Onboarding step 1 — updated" + }, + "description": { + "description": "Updated description of what the screenshot shows. Helps translators understand the UI context without opening the image.", + "type": "string", + "example": "First step of the onboarding flow after the redesign" + } } } - }, + } + } + }, + "responses": { + "200": { + "description": "The screenshot was updated successfully. Returns the full screenshot object.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" @@ -21351,73 +21373,73 @@ "X-Rate-Limit-Reset": { "$ref": "#/components/headers/X-Rate-Limit-Reset" } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/screenshot" + }, + "example": { + "id": "d2e056aa9e70b01121f41693e344f5ee", + "name": "Onboarding step 1 — updated", + "description": "First step of the onboarding flow after the redesign", + "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + "created_at": "2024-03-15T10:22:31Z", + "updated_at": "2024-06-10T09:15:44Z", + "markers_count": 3 + } + } } }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "Bad request. Returned when the request body cannot be parsed (for example, malformed JSON) or a parameter value is of an unexpected type. Fix the request payload and retry." }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "Unauthorized. The access token is missing, expired, or invalid. Provide a valid token in the `Authorization` header or via the `access_token` query parameter." }, "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": "Forbidden. Returned in three cases: (1) the access token lacks the `write` scope; (2) the authenticated user does not have Manage permissions on this project; or (3) the account does not have the Attachable Screenshots feature enabled. Check your token scopes, your project role, and your subscription plan." }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "Not found. No screenshot with the given `id` exists in the specified project, or the `project_id` does not match a project accessible to the authenticated user. Verify both identifiers and retry." }, "422": { - "$ref": "#/components/responses/422" + "$ref": "#/components/responses/422", + "description": "Unprocessable entity. The screenshot could not be saved due to a validation error — most commonly because another screenshot in the project already has the same name (case-insensitive). Read the `errors` array in the response body for the specific field and message, then adjust the request accordingly." }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "Too many requests. Your account has exceeded the API rate limit. Wait until the time indicated in the `X-Rate-Limit-Reset` 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 -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Onboarding step 1 — updated\",\n \"description\": \"First step of the onboarding flow after the redesign\"\n }'\n\n# Expected response (200 OK):\n# {\n# \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n# \"name\": \"Onboarding step 1 — updated\",\n# \"description\": \"First step of the onboarding flow after the redesign\",\n# \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n# \"created_at\": \"2024-03-15T10:22:31Z\",\n# \"updated_at\": \"2024-06-10T09:15:44Z\",\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 :project_id \\\n --id :id \\\n --data '{\"name\":\"Onboarding step 1 — updated\",\"description\":\"First step of the onboarding flow after the redesign\"}' \\\n --access_token \n\n# Expected response (200 OK):\n# {\n# \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n# \"name\": \"Onboarding step 1 — updated\",\n# \"description\": \"First step of the onboarding flow after the redesign\",\n# \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n# \"created_at\": \"2024-03-15T10:22:31Z\",\n# \"updated_at\": \"2024-06-10T09:15:44Z\",\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", + "security": [ + { + "Basic": [] + }, + { + "Token": [] + }, + { + "OAuthAccessToken": [ + "write" + ] } - }, - "x-cli-version": "2.5" + ] }, "delete": { "summary": "Delete a screenshot", diff --git a/paths/screenshots/update.yaml b/paths/screenshots/update.yaml index df4f3e29..f101d5fb 100644 --- a/paths/screenshots/update.yaml +++ b/paths/screenshots/update.yaml @@ -1,20 +1,78 @@ --- summary: Update a screenshot -description: Update an existing screenshot. +description: | + Updates the name or description of an existing screenshot in a Phrase Strings project. + + Use this operation when you need to correct a screenshot's display name or clarify its description + for translators. Screenshots in Phrase Strings are images attached to translation keys to provide + visual context: they help translators understand where a string appears in the UI. Each screenshot + can have zero or more markers (`markers_count`) linking it to specific translation keys. + + **Important constraints and pitfalls:** + - The `name` must be unique within the project (case-insensitive). Submitting a name that + already exists on another screenshot in the same project returns a 422 error. + - This endpoint does **not** accept a file upload. Replacing the image file (`filename`) is not + supported via the update operation; to change the image, delete the screenshot and create a + new one. + - All body parameters are optional. Send only the fields you want to change; omitted fields are + left unchanged. + - The Attachable Screenshots feature must be enabled on the account. Requests from accounts + without this feature receive a 403 response regardless of user permissions. + - Only users with Manage permissions on the project may update screenshots. Users with only Read + access receive a 403 response. + + On success, a `screenshots:update` event is dispatched to configured webhooks. + + **Error codes:** Phrase Strings does not return stable machine-readable error code strings beyond + the HTTP status code. Use the HTTP status to branch error handling; read the `message` field in + the response body for a human-readable explanation. + + | HTTP status | Condition | + |-------------|-----------| + | 400 | Malformed request body (unparseable JSON) or a parameter value is of an unexpected type. | + | 401 | Missing or invalid authentication credentials, or invalid OTP code. | + | 403 | Token lacks the `write` scope; caller lacks manage permission; or account plan does not include the Screenshots feature. | + | 404 | The project or screenshot does not exist or is not accessible to the caller. | + | 422 | Screenshot attributes failed model validation (for example, a blank or duplicate name). | + | 429 | The caller has exceeded their per-minute request quota or concurrent-request limit. | operationId: screenshot/update tags: -- Screenshots + - Screenshots parameters: -- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" -- "$ref": "../../parameters.yaml#/project_id" -- "$ref": "../../parameters.yaml#/id" + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/project_id" + - "$ref": "../../parameters.yaml#/id" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: screenshot/update/parameters + description: All properties are optional. Include only the fields you want to update. + properties: + branch: + description: >- + Name of the branch to operate on. When supplied, the request is scoped to that + branch project rather than the main project. Omit to operate on the main project. + type: string + example: my-feature-branch + name: + description: >- + New display name for the screenshot. Must be unique within the project + (case-insensitive). If another screenshot in the project already uses this name, + the request fails with 422. + type: string + example: Onboarding step 1 — updated + description: + description: >- + Updated description of what the screenshot shows. Helps translators understand the + UI context without opening the image. + type: string + example: First step of the onboarding flow after the redesign responses: '200': - description: OK - content: - application/json: - schema: - "$ref": "../../schemas/screenshot.yaml#/screenshot" + description: The screenshot was updated successfully. Returns the full screenshot object. headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -22,59 +80,96 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" X-Rate-Limit-Reset: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + content: + application/json: + schema: + "$ref": "../../schemas/screenshot.yaml#/screenshot" + example: + id: d2e056aa9e70b01121f41693e344f5ee + name: Onboarding step 1 — updated + description: First step of the onboarding flow after the redesign + screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png + created_at: '2024-03-15T10:22:31Z' + updated_at: '2024-06-10T09:15:44Z' + markers_count: 3 '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" + description: >- + Bad request. Returned when the request body cannot be parsed (for example, malformed JSON) + or a parameter value is of an unexpected type. Fix the request payload and retry. '401': "$ref": "../../responses.yaml#/401" + description: >- + Unauthorized. The access token is missing, expired, or invalid. Provide a valid token in + the `Authorization` header or via the `access_token` query parameter. '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: >- + Forbidden. Returned in three cases: (1) the access token lacks the `write` scope; + (2) the authenticated user does not have Manage permissions on this project; or + (3) the account does not have the Attachable Screenshots feature enabled. Check your + token scopes, your project role, and your subscription plan. + '404': + "$ref": "../../responses.yaml#/404" + description: >- + Not found. No screenshot with the given `id` exists in the specified project, or the + `project_id` does not match a project accessible to the authenticated user. Verify both + identifiers and retry. '422': "$ref": "../../responses.yaml#/422" + description: >- + Unprocessable entity. The screenshot could not be saved due to a validation error — most + commonly because another screenshot in the project already has the same name + (case-insensitive). Read the `errors` array in the response body for the specific field + and message, then adjust the request accordingly. '429': "$ref": "../../responses.yaml#/429" + description: >- + Too many requests. Your account has exceeded the API rate limit. Wait until the time + indicated in the `X-Rate-Limit-Reset` 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 -- 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" + - lang: Curl + source: |- + curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \ + -u USERNAME_OR_ACCESS_TOKEN \ + -X PATCH \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Onboarding step 1 — updated", + "description": "First step of the onboarding flow after the redesign" + }' + + # Expected response (200 OK): + # { + # "id": "d2e056aa9e70b01121f41693e344f5ee", + # "name": "Onboarding step 1 — updated", + # "description": "First step of the onboarding flow after the redesign", + # "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + # "created_at": "2024-03-15T10:22:31Z", + # "updated_at": "2024-06-10T09:15:44Z", + # "markers_count": 3 + # } + - lang: CLI v2 + source: |- + phrase screenshots update \ + --project_id :project_id \ + --id :id \ + --data '{"name":"Onboarding step 1 — updated","description":"First step of the onboarding flow after the redesign"}' \ + --access_token + + # Expected response (200 OK): + # { + # "id": "d2e056aa9e70b01121f41693e344f5ee", + # "name": "Onboarding step 1 — updated", + # "description": "First step of the onboarding flow after the redesign", + # "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + # "created_at": "2024-03-15T10:22:31Z", + # "updated_at": "2024-06-10T09:15:44Z", + # "markers_count": 3 + # } x-cli-version: '2.5' +security: + - Basic: [] + - Token: [] + - OAuthAccessToken: + - write