diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..99064338 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -21132,7 +21132,7 @@ }, "post": { "summary": "Create a screenshot", - "description": "Create a new screenshot.", + "description": "Uploads a new screenshot image to the specified project, making it available for\ntranslators as visual context. Screenshots are image files associated with a project\nand can subsequently be linked to one or more translation keys via screenshot markers.\n\nUse this endpoint when you want to provide translators with on-screen context for\nthe strings they are working on. After creating a screenshot, use the screenshot\nmarkers endpoint (`POST /projects/{project_id}/screenshots/{screenshot_id}/markers`)\nto associate the screenshot with specific translation keys.\n\nThe `id` field in the response is the screenshot's string code (not a numeric primary\nkey). Pass this value as the `screenshot_id` path segment in subsequent marker or\nscreenshot calls.\n\n**Accepted formats:** JPG, JPEG, GIF, and PNG. The maximum file size is 10 MB by\ndefault (configurable per deployment).\n\n**Name uniqueness:** Screenshot names must be unique within the project\n(case-insensitive). Attempting to create a duplicate name returns a 422 error.\n\n**File upload:** The request body must be sent as `multipart/form-data`. The `filename`\nfield is required; omitting it or uploading a file that cannot be processed by the\nimage pipeline will return a 422 with an error on the `filename` field.\n\n**Side effects:** A `screenshots:create` event is dispatched upon success, which may\ntrigger configured webhook notifications for your project.\n\n**Access control:** The requesting token must carry the `write` OAuth scope, and the\nauthenticated user must have manage permission on the Screenshot resource within the\nproject. Protected projects cannot receive new screenshots regardless of the user's\nrole, returning a 403. Access is also gated on the Attachable Screenshots feature\nbeing enabled for the account; a 403 is returned when the feature is unavailable on\nthe account's plan. When the Phrase Sketch Plugin user-agent is detected and the\naccount's Sketch Plugin feature is not enabled, a 403 is also returned.\n\n**Branches:** Pass the `branch` parameter in the request body to create the screenshot\nwithin a specific branch context. Omit it to create against the main branch.\n", "operationId": "screenshot/create", "tags": [ "Screenshots" @@ -21152,6 +21152,15 @@ "application/json": { "schema": { "$ref": "#/components/schemas/screenshot" + }, + "example": { + "id": "d2e056aa9e70b01121f41693e344f5ee", + "name": "Onboarding step 1", + "description": "First step of the user onboarding flow showing the project selection screen", + "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png", + "created_at": "2024-03-15T10:22:31Z", + "updated_at": "2024-03-18T14:05:12Z", + "markers_count": 0 } } }, @@ -21168,33 +21177,38 @@ } }, "400": { - "$ref": "#/components/responses/400" + "$ref": "#/components/responses/400", + "description": "Bad request. Returned when the request is malformed, a required parameter is\nmissing, or the request body cannot be parsed. Verify that all required fields\nare present and the multipart form data is correctly encoded.\n" }, "401": { - "$ref": "#/components/responses/401" + "$ref": "#/components/responses/401", + "description": "Unauthorized. The access token is missing, expired, or invalid. Provide a valid\ntoken via the `Authorization` header or the `access_token` query parameter.\n" }, "403": { "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to create screenshots in this project, or when the account does not have the Attachable Screenshots feature." + "description": "Forbidden. Returned when:\n- The access token lacks the `write` OAuth scope, or the user's account is unconfirmed.\n- The authenticated user does not have manage permission on screenshots in this project.\n- The project is protected, which prevents creating new screenshots.\n- The account does not have the Attachable Screenshots feature enabled on its plan.\n- The request originates from the Phrase Sketch Plugin and the account's Sketch Plugin\n feature is not enabled.\n" }, "404": { - "$ref": "#/components/responses/404" + "$ref": "#/components/responses/404", + "description": "Not found. The specified project does not exist or is not accessible with the\nprovided credentials. Verify the `project_id` path parameter.\n" }, "422": { - "$ref": "#/components/responses/422" + "$ref": "#/components/responses/422", + "description": "Unprocessable entity. Returned when validation fails. Common causes:\n- `name` is blank or already taken by another screenshot in this project\n (names must be unique within a project, case-insensitive).\n- `filename` is missing or the uploaded file could not be processed.\n- The uploaded file is not a supported image format (JPG, JPEG, GIF, or PNG).\n- The uploaded file exceeds the maximum allowed size (10 MB by default).\nThe response body contains a `message` and an `errors` array identifying the\naffected field and the reason.\n" }, "429": { - "$ref": "#/components/responses/429" + "$ref": "#/components/responses/429", + "description": "Too many requests. The rate limit for this endpoint has been exceeded. Wait until\nthe time indicated by the `X-Rate-Limit-Reset` response header before retrying.\n" } }, "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\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/3d7ce831a3e9e1b843dc16d36ee5b9f4/screenshots\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -F \"branch=my-feature-branch\" \\\n -F \"name=Onboarding step 1\" \\\n -F \"description=First step of the user onboarding flow\" \\\n -F \"filename=@/path/to/screenshot.png\"" }, { "lang": "CLI v2", - "source": "phrase screenshots create \\\n--project_id \\\n--branch \"my-feature-branch\" --name \"A screenshot name\" --description \"A screenshot description\" --filename \"/path/to/my/screenshot.png\" \\\n--access_token " + "source": "phrase screenshots create \\\n--project_id 3d7ce831a3e9e1b843dc16d36ee5b9f4 \\\n--branch \"my-feature-branch\" \\\n--name \"Onboarding step 1\" \\\n--description \"First step of the user onboarding flow\" \\\n--filename \"/path/to/screenshot.png\" \\\n--access_token " } ], "requestBody": { @@ -21204,27 +21218,29 @@ "schema": { "type": "object", "title": "screenshot/create/parameters", + "required": [ + "filename" + ], "properties": { "branch": { - "description": "specify the branch to use", + "description": "Branch to create the screenshot in. Omit to target the main branch.", "type": "string", "example": "my-feature-branch" }, "name": { - "description": "Name of the screenshot", + "description": "Human-readable name for the screenshot shown in the Phrase dashboard and to\ntranslators. Must be unique within the project (case-insensitive). When\nomitted, a name is derived from the uploaded file's name.\n", "type": "string", - "example": "A screenshot name" + "example": "Onboarding step 1" }, "description": { - "description": "Description of the screenshot", + "description": "Optional longer description providing additional context about what the screenshot depicts.", "type": "string", - "example": "A screenshot description" + "example": "First step of the user onboarding flow showing the project selection screen" }, "filename": { - "description": "Screenshot file", + "description": "The screenshot image file to upload. Accepted formats: JPG, JPEG, GIF, PNG.\nMaximum file size is 10 MB. Pass the file using multipart form data\n(e.g., `@/path/to/image.png` with curl). If the file is missing or cannot\nbe processed, a 422 is returned with an error on the `filename` field.\n", "type": "string", - "format": "binary", - "example": "/path/to/my/screenshot.png" + "format": "binary" } } } diff --git a/paths/screenshots/create.yaml b/paths/screenshots/create.yaml index 94876a43..0d8ac245 100644 --- a/paths/screenshots/create.yaml +++ b/paths/screenshots/create.yaml @@ -1,6 +1,42 @@ --- summary: Create a screenshot -description: Create a new screenshot. +description: | + Uploads a new screenshot image to the specified project, making it available for + translators as visual context. Screenshots are image files associated with a project + and can subsequently be linked to one or more translation keys via screenshot markers. + + Use this endpoint when you want to provide translators with on-screen context for + the strings they are working on. After creating a screenshot, use the screenshot + markers endpoint (`POST /projects/{project_id}/screenshots/{screenshot_id}/markers`) + to associate the screenshot with specific translation keys. + + The `id` field in the response is the screenshot's string code (not a numeric primary + key). Pass this value as the `screenshot_id` path segment in subsequent marker or + screenshot calls. + + **Accepted formats:** JPG, JPEG, GIF, and PNG. The maximum file size is 10 MB by + default (configurable per deployment). + + **Name uniqueness:** Screenshot names must be unique within the project + (case-insensitive). Attempting to create a duplicate name returns a 422 error. + + **File upload:** The request body must be sent as `multipart/form-data`. The `filename` + field is required; omitting it or uploading a file that cannot be processed by the + image pipeline will return a 422 with an error on the `filename` field. + + **Side effects:** A `screenshots:create` event is dispatched upon success, which may + trigger configured webhook notifications for your project. + + **Access control:** The requesting token must carry the `write` OAuth scope, and the + authenticated user must have manage permission on the Screenshot resource within the + project. Protected projects cannot receive new screenshots regardless of the user's + role, returning a 403. Access is also gated on the Attachable Screenshots feature + being enabled for the account; a 403 is returned when the feature is unavailable on + the account's plan. When the Phrase Sketch Plugin user-agent is detected and the + account's Sketch Plugin feature is not enabled, a 403 is also returned. + + **Branches:** Pass the `branch` parameter in the request body to create the screenshot + within a specific branch context. Omit it to create against the main branch. operationId: screenshot/create tags: - Screenshots @@ -14,6 +50,14 @@ responses: application/json: schema: "$ref": "../../schemas/screenshot.yaml#/screenshot" + example: + id: d2e056aa9e70b01121f41693e344f5ee + name: Onboarding step 1 + description: First step of the user onboarding flow showing the project selection screen + screenshot_url: https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png + created_at: '2024-03-15T10:22:31Z' + updated_at: '2024-03-18T14:05:12Z' + markers_count: 0 headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -23,32 +67,64 @@ responses: "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" + description: | + Bad request. Returned when the request is malformed, a required parameter is + missing, or the request body cannot be parsed. Verify that all required fields + are present and the multipart form data is correctly encoded. '401': "$ref": "../../responses.yaml#/401" + description: | + Unauthorized. The access token is missing, expired, or invalid. Provide a valid + token via the `Authorization` header or 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 create screenshots in this project, or when the account does not have the Attachable Screenshots feature. + description: | + Forbidden. Returned when: + - The access token lacks the `write` OAuth scope, or the user's account is unconfirmed. + - The authenticated user does not have manage permission on screenshots in this project. + - The project is protected, which prevents creating new screenshots. + - The account does not have the Attachable Screenshots feature enabled on its plan. + - The request originates from the Phrase Sketch Plugin and the account's Sketch Plugin + feature is not enabled. + '404': + "$ref": "../../responses.yaml#/404" + description: | + Not found. The specified project does not exist or is not accessible with the + provided credentials. Verify the `project_id` path parameter. '422': "$ref": "../../responses.yaml#/422" + description: | + Unprocessable entity. Returned when validation fails. Common causes: + - `name` is blank or already taken by another screenshot in this project + (names must be unique within a project, case-insensitive). + - `filename` is missing or the uploaded file could not be processed. + - The uploaded file is not a supported image format (JPG, JPEG, GIF, or PNG). + - The uploaded file exceeds the maximum allowed size (10 MB by default). + The response body contains a `message` and an `errors` array identifying the + affected field and the reason. '429': "$ref": "../../responses.yaml#/429" + description: | + Too many requests. The rate limit for this endpoint has been exceeded. Wait until + the time indicated by 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" \ + curl "https://api.phrase.com/v2/projects/3d7ce831a3e9e1b843dc16d36ee5b9f4/screenshots" \ -u USERNAME_OR_ACCESS_TOKEN \ -X POST \ - -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=Onboarding step 1" \ + -F "description=First step of the user onboarding flow" \ + -F "filename=@/path/to/screenshot.png" - lang: CLI v2 source: |- phrase screenshots create \ - --project_id \ - --branch "my-feature-branch" --name "A screenshot name" --description "A screenshot description" --filename "/path/to/my/screenshot.png" \ + --project_id 3d7ce831a3e9e1b843dc16d36ee5b9f4 \ + --branch "my-feature-branch" \ + --name "Onboarding step 1" \ + --description "First step of the user onboarding flow" \ + --filename "/path/to/screenshot.png" \ --access_token requestBody: required: true @@ -57,22 +133,30 @@ requestBody: schema: type: object title: screenshot/create/parameters + required: + - filename properties: branch: - description: specify the branch to use + description: Branch to create the screenshot in. Omit to target the main branch. type: string example: my-feature-branch name: - description: Name of the screenshot + description: | + Human-readable name for the screenshot shown in the Phrase dashboard and to + translators. Must be unique within the project (case-insensitive). When + omitted, a name is derived from the uploaded file's name. type: string - example: A screenshot name + example: Onboarding step 1 description: - description: Description of the screenshot + description: Optional longer description providing additional context about what the screenshot depicts. type: string - example: A screenshot description + example: First step of the user onboarding flow showing the project selection screen filename: - description: Screenshot file + description: | + The screenshot image file to upload. Accepted formats: JPG, JPEG, GIF, PNG. + Maximum file size is 10 MB. Pass the file using multipart form data + (e.g., `@/path/to/image.png` with curl). If the file is missing or cannot + be processed, a 422 is returned with an error on the `filename` field. type: string format: binary - example: "/path/to/my/screenshot.png" x-cli-version: '2.5'