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

doc/compiled.json

@@ -21033,7 +21033,7 @@
     "/projects/{project_id}/screenshots": {
       "get": {
         "summary": "List screenshots",
-        "description": "List all screenshots for the given project.",
+        "description": "Returns all screenshots uploaded to the given project. Screenshots are UI images that provide visual context for translators, helping them understand where a translation string appears in the product interface.\n\nUse this endpoint to browse existing screenshots before creating markers, or to audit which screenshots belong to a project. Filtering by key_id narrows results to screenshots that have at least one marker linked to that key.\n\nAccess requires the Attachable Screenshots feature to be enabled on the account and the read scope on the access token. The read-only scope is sufficient — write access is not required. When key_id is supplied and no key with that code exists in the project, the request returns 404.\n\nThe X-PhraseApp-OTP header (One-Time Password) is optional and required only when the access token belongs to a user with two-factor authentication enforced at request time.\n\nError codes follow the UPPER_SNAKE_CASE format (for example, FEATURE_UNAVAILABLE, INSUFFICIENT_SCOPE) and are returned in the message field of the error response body alongside a human-readable description.\n",
         "operationId": "screenshots/list",
         "tags": [
           "Screenshots"
@@ -21052,21 +21052,24 @@
             "$ref": "#/components/parameters/per_page"
           },
           {
-            "description": "specify the branch to use",
+            "description": "Branch to use instead of the project default branch. When omitted, results are scoped to the default branch.",
             "example": "my-feature-branch",
             "name": "branch",
             "in": "query",
+            "required": false,
             "schema": {
               "type": "string"
             }
           },
           {
-            "description": "filter by key",
+            "description": "Filter results to screenshots that have at least one marker linked to the translation key with this code. Must be a 32-character lowercase hexadecimal string matching a key in the project. Returns 404 when no key with this code exists.",
             "example": "abcd1234cdef1234abcd1234cdef1234",
             "name": "key_id",
             "in": "query",
+            "required": false,
             "schema": {
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-f]{32}$"
             }
           }
         ],
@@ -21102,30 +21105,35 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/400"
+            "$ref": "#/components/responses/400",
+            "description": "Bad request. Returned when a supplied parameter value is invalid — for example when key_id does not match the required 32-character hexadecimal format. Correct the parameter value and retry the request."
           },
           "401": {
-            "$ref": "#/components/responses/401"
+            "$ref": "#/components/responses/401",
+            "description": "Unauthorized. Returned when no valid access token is provided or the token has expired. Supply a valid access token in the Authorization header or as the access_token query parameter and retry."
           },
           "403": {
             "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list screenshots in this project, or when the account does not have the Attachable Screenshots feature."
+            "description": "Forbidden. Returned when the access token lacks the read scope, when the authenticated user does not have read permission on screenshots in this project, or when the Attachable Screenshots feature is not enabled on the account. Verify that the token has the read scope and that the feature is available on your subscription plan."
           },
           "404": {
             "$ref": "#/components/responses/404"
           },
           "429": {
-            "$ref": "#/components/responses/429"
+            "$ref": "#/components/responses/429",
+            "description": "Too many requests. Returned when the account or token rate limit has been exceeded. Wait until the time indicated by the X-Rate-Limit-Reset header before sending further requests."
           }
         },
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN",
+            "response": "[\n  {\n    \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n    \"name\": \"home_screen\",\n    \"description\": \"Main landing page hero screenshot\",\n    \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n    \"created_at\": \"2024-03-15T10:30:00.000Z\",\n    \"updated_at\": \"2024-03-15T10:30:00.000Z\",\n    \"markers_count\": 3\n  },\n  {\n    \"id\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n    \"name\": \"settings_page\",\n    \"description\": \"Account settings form\",\n    \"screenshot_url\": \"https://assets.phrase.com/screenshots/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4.png\",\n    \"created_at\": \"2024-03-10T08:00:00.000Z\",\n    \"updated_at\": \"2024-03-12T14:22:00.000Z\",\n    \"markers_count\": 0\n  }\n]"
           },
           {
             "lang": "CLI v2",
-            "source": "phrase screenshots list \\\n--project_id <project_id> \\\n--branch my-feature-branch \\\n--access_token <token>"
+            "source": "phrase screenshots list \\\n--project_id <project_id> \\\n--branch my-feature-branch \\\n--access_token <token>",
+            "response": "[\n  {\n    \"id\": \"d2e056aa9e70b01121f41693e344f5ee\",\n    \"name\": \"home_screen\",\n    \"description\": \"Main landing page hero screenshot\",\n    \"screenshot_url\": \"https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png\",\n    \"created_at\": \"2024-03-15T10:30:00.000Z\",\n    \"updated_at\": \"2024-03-15T10:30:00.000Z\",\n    \"markers_count\": 3\n  }\n]"
           }
         ],
         "x-cli-version": "2.5"

paths/screenshots/index.yaml

@@ -1,6 +1,15 @@
 ---
 summary: List screenshots
-description: List all screenshots for the given project.
+description: |
+  Returns all screenshots uploaded to the given project. Screenshots are UI images that provide visual context for translators, helping them understand where a translation string appears in the product interface.
+
+  Use this endpoint to browse existing screenshots before creating markers, or to audit which screenshots belong to a project. Filtering by key_id narrows results to screenshots that have at least one marker linked to that key.
+
+  Access requires the Attachable Screenshots feature to be enabled on the account and the read scope on the access token. The read-only scope is sufficient — write access is not required. When key_id is supplied and no key with that code exists in the project, the request returns 404.
+
+  The X-PhraseApp-OTP header (One-Time Password) is optional and required only when the access token belongs to a user with two-factor authentication enforced at request time.
+
+  Error codes follow the UPPER_SNAKE_CASE format (for example, FEATURE_UNAVAILABLE, INSUFFICIENT_SCOPE) and are returned in the message field of the error response body alongside a human-readable description.
 operationId: screenshots/list
 tags:
 - Screenshots
@@ -9,18 +18,21 @@ parameters:
 - "$ref": "../../parameters.yaml#/project_id"
 - "$ref": "../../parameters.yaml#/page"
 - "$ref": "../../parameters.yaml#/per_page"
-- description: specify the branch to use
+- description: Branch to use instead of the project default branch. When omitted, results are scoped to the default branch.
   example: my-feature-branch
   name: branch
   in: query
+  required: false
   schema:
     type: string
-- description: filter by key
+- description: Filter results to screenshots that have at least one marker linked to the translation key with this code. Must be a 32-character lowercase hexadecimal string matching a key in the project. Returns 404 when no key with this code exists.
   example: abcd1234cdef1234abcd1234cdef1234
   name: key_id
   in: query
+  required: false
   schema:
     type: string
+    pattern: "^[0-9a-f]{32}$"
 responses:
   '200':
     description: OK
@@ -43,24 +55,74 @@ responses:
         "$ref": "../../headers.yaml#/Pagination"
   '400':
     "$ref": "../../responses.yaml#/400"
-  '404':
-    "$ref": "../../responses.yaml#/404"
+    description: >-
+      Bad request. Returned when a supplied parameter value is invalid — for
+      example when key_id does not match the required 32-character hexadecimal
+      format. Correct the parameter value and retry the request.
   '401':
     "$ref": "../../responses.yaml#/401"
+    description: >-
+      Unauthorized. Returned when no valid access token is provided or the
+      token has expired. Supply a valid access token in the Authorization
+      header or as the access_token query parameter and retry.
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list screenshots in this project, or when the account does not have the Attachable Screenshots feature.
+    description: >-
+      Forbidden. Returned when the access token lacks the read scope, when
+      the authenticated user does not have read permission on screenshots in
+      this project, or when the Attachable Screenshots feature is not enabled
+      on the account. Verify that the token has the read scope and that the
+      feature is available on your subscription plan.
+  '404':
+    "$ref": "../../responses.yaml#/404"
   '429':
     "$ref": "../../responses.yaml#/429"
+    description: >-
+      Too many requests. Returned when the account or token rate limit has
+      been exceeded. Wait until the time indicated by the X-Rate-Limit-Reset
+      header before sending further requests.
 x-code-samples:
 - lang: Curl
   source: |-
     curl "https://api.phrase.com/v2/projects/:project_id/screenshots?branch=my-feature-branch" \
       -u USERNAME_OR_ACCESS_TOKEN
+  response: |-
+    [
+      {
+        "id": "d2e056aa9e70b01121f41693e344f5ee",
+        "name": "home_screen",
+        "description": "Main landing page hero screenshot",
+        "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png",
+        "created_at": "2024-03-15T10:30:00.000Z",
+        "updated_at": "2024-03-15T10:30:00.000Z",
+        "markers_count": 3
+      },
+      {
+        "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
+        "name": "settings_page",
+        "description": "Account settings form",
+        "screenshot_url": "https://assets.phrase.com/screenshots/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4.png",
+        "created_at": "2024-03-10T08:00:00.000Z",
+        "updated_at": "2024-03-12T14:22:00.000Z",
+        "markers_count": 0
+      }
+    ]
 - lang: CLI v2
   source: |-
     phrase screenshots list \
     --project_id <project_id> \
     --branch my-feature-branch \
     --access_token <token>
+  response: |-
+    [
+      {
+        "id": "d2e056aa9e70b01121f41693e344f5ee",
+        "name": "home_screen",
+        "description": "Main landing page hero screenshot",
+        "screenshot_url": "https://assets.phrase.com/screenshots/d2e056aa9e70b01121f41693e344f5ee.png",
+        "created_at": "2024-03-15T10:30:00.000Z",
+        "updated_at": "2024-03-15T10:30:00.000Z",
+        "markers_count": 3
+      }
+    ]
 x-cli-version: '2.5'