feat(API): improve post /projects/{project_id}/screenshots documentation

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 <project_id> \\\n--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 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 <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"
                   }
                 }
               }

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 <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 <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'