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

doc/compiled.json

@@ -21237,7 +21237,7 @@
     "/projects/{project_id}/screenshots/{id}": {
       "get": {
         "summary": "Get a single screenshot",
-        "description": "Get details on a single screenshot for a given project.",
+        "description": "Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects.\n\nThe Attachable Screenshots feature must be enabled on the account.\n",
         "operationId": "screenshot/show",
         "tags": [
           "Screenshots"
@@ -21257,6 +21257,7 @@
             "example": "my-feature-branch",
             "name": "branch",
             "in": "query",
+            "required": false,
             "schema": {
               "type": "string"
             }
@@ -21285,30 +21286,34 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/400"
+            "$ref": "#/components/responses/400",
+            "description": "BAD_REQUEST: malformed request parameters."
           },
           "401": {
-            "$ref": "#/components/responses/401"
+            "$ref": "#/components/responses/401",
+            "description": "UNAUTHORIZED: missing or invalid access token."
           },
           "403": {
             "$ref": "#/components/responses/403",
-            "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this screenshot, or when the account does not have the Attachable Screenshots feature."
+            "description": "FORBIDDEN: the access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account."
           },
           "404": {
-            "$ref": "#/components/responses/404"
+            "$ref": "#/components/responses/404",
+            "description": "NOT_FOUND: the project or screenshot does not exist under the given identifiers."
           },
           "429": {
-            "$ref": "#/components/responses/429"
+            "$ref": "#/components/responses/429",
+            "description": "RATE_LIMIT_EXCEEDED: too many requests. Wait for the reset time indicated by X-Rate-Limit-Reset before retrying."
           }
         },
         "x-code-samples": [
           {
             "lang": "Curl",
-            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
+            "source": "curl \"https://api.phrase.com/v2/projects/:project_id/screenshots/:id\" \\\n  -u USERNAME_OR_ACCESS_TOKEN"
           },
           {
             "lang": "CLI v2",
-            "source": "phrase screenshots show \\\n--project_id <project_id> \\\n--id <id> \\\n--branch my-feature-branch \\\n--access_token <token>"
+            "source": "phrase screenshots show \\\n--project_id <project_id> \\\n--id <id> \\\n--access_token <token>"
           }
         ],
         "x-cli-version": "2.5"

paths/screenshots/show.yaml

@@ -1,6 +1,9 @@
 ---
 summary: Get a single screenshot
-description: Get details on a single screenshot for a given project.
+description: |
+  Returns a single screenshot belonging to the specified project. Use this to retrieve the screenshot's name, description, hosted image URL, and marker count after uploading, or before creating, updating, or inspecting its markers. The response is a synchronous, idempotent read — repeated calls return the same record without side effects.
+
+  The Attachable Screenshots feature must be enabled on the account.
 operationId: screenshot/show
 tags:
 - Screenshots
@@ -12,6 +15,7 @@ parameters:
   example: my-feature-branch
   name: branch
   in: query
+  required: false
   schema:
     type: string
 responses:
@@ -30,25 +34,28 @@ responses:
         "$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
   '400':
     "$ref": "../../responses.yaml#/400"
-  '404':
-    "$ref": "../../responses.yaml#/404"
+    description: "BAD_REQUEST: malformed request parameters."
   '401':
     "$ref": "../../responses.yaml#/401"
+    description: "UNAUTHORIZED: missing or invalid access token."
   '403':
     "$ref": "../../responses.yaml#/403"
-    description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this screenshot, or when the account does not have the Attachable Screenshots feature.
+    description: "FORBIDDEN: the access token lacks the read scope, the requesting user does not have read access to the project, or the Attachable Screenshots feature is not enabled on the account."
+  '404':
+    "$ref": "../../responses.yaml#/404"
+    description: "NOT_FOUND: the project or screenshot does not exist under the given identifiers."
   '429':
     "$ref": "../../responses.yaml#/429"
+    description: "RATE_LIMIT_EXCEEDED: too many requests. Wait for the reset time indicated by X-Rate-Limit-Reset before retrying."
 x-code-samples:
 - lang: Curl
   source: |-
-    curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id?branch=my-feature-branch" \
+    curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
       -u USERNAME_OR_ACCESS_TOKEN
 - lang: CLI v2
   source: |-
     phrase screenshots show \
     --project_id <project_id> \
     --id <id> \
-    --branch my-feature-branch \
     --access_token <token>
 x-cli-version: '2.5'