feat(scrape): support custom screenshot headers (#1169)

Stainless-Generated-From: 5b13d3673c7a039f7030a8ebfe760f1a1108c621

Author: stlc-bot

src/context/dev/resources/web.py

@@ -712,6 +712,7 @@ def screenshot(
         domain: str | Omit = omit,
         full_screenshot: Literal["true", "false"] | Omit = omit,
         handle_cookie_popup: bool | Omit = omit,
+        headers: Dict[str, str] | Omit = omit,
         max_age_ms: Optional[int] | Omit = omit,
         page: Literal["login", "signup", "blog", "careers", "pricing", "terms", "privacy", "contact"] | Omit = omit,
         scroll_offset: Optional[int] | Omit = omit,
@@ -759,6 +760,14 @@ def screenshot(
               dismiss cookie banner before capture. If 'false' or not provided, captures the
               page without that step.
 
+          headers: Optional outbound HTTP headers, using the same JSON object or deep-object query
+              format as other scrape endpoints (for example headers[Authorization]=Bearer
+              token). Headers are scoped to the target origin during capture. For domain/page
+              requests, discovery receives no custom headers and only pages on the resolved
+              origin are eligible. Non-empty headers bypass screenshot caching and return an
+              in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+              headers.
+
           max_age_ms: Return a cached screenshot if a prior screenshot for the same parameters exists
               and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when
               omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
@@ -821,6 +830,7 @@ def screenshot(
                         "domain": domain,
                         "full_screenshot": full_screenshot,
                         "handle_cookie_popup": handle_cookie_popup,
+                        "headers": headers,
                         "max_age_ms": max_age_ms,
                         "page": page,
                         "scroll_offset": scroll_offset,
@@ -2862,6 +2872,7 @@ def web_scrape_screenshot(
         | Omit = omit,
         full_screenshot: Literal["true", "false"] | Omit = omit,
         handle_cookie_popup: bool | Omit = omit,
+        headers: Dict[str, str] | Omit = omit,
         max_age_ms: Optional[int] | Omit = omit,
         scroll_offset: Optional[int] | Omit = omit,
         tags: SequenceNotStr[str] | Omit = omit,
@@ -2905,6 +2916,14 @@ def web_scrape_screenshot(
               dismiss cookie banner before capture. If 'false' or not provided, captures the
               page without that step.
 
+          headers: Optional outbound HTTP headers, using the same JSON object or deep-object query
+              format as other scrape endpoints (for example headers[Authorization]=Bearer
+              token). Headers are scoped to the target origin during capture. For domain/page
+              requests, discovery receives no custom headers and only pages on the resolved
+              origin are eligible. Non-empty headers bypass screenshot caching and return an
+              in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+              headers.
+
           max_age_ms: Return a cached screenshot if a prior screenshot for the same parameters exists
               and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when
               omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
@@ -2960,6 +2979,7 @@ def web_scrape_screenshot(
                         "country": country,
                         "full_screenshot": full_screenshot,
                         "handle_cookie_popup": handle_cookie_popup,
+                        "headers": headers,
                         "max_age_ms": max_age_ms,
                         "scroll_offset": scroll_offset,
                         "tags": tags,
@@ -3734,6 +3754,7 @@ async def screenshot(
         domain: str | Omit = omit,
         full_screenshot: Literal["true", "false"] | Omit = omit,
         handle_cookie_popup: bool | Omit = omit,
+        headers: Dict[str, str] | Omit = omit,
         max_age_ms: Optional[int] | Omit = omit,
         page: Literal["login", "signup", "blog", "careers", "pricing", "terms", "privacy", "contact"] | Omit = omit,
         scroll_offset: Optional[int] | Omit = omit,
@@ -3781,6 +3802,14 @@ async def screenshot(
               dismiss cookie banner before capture. If 'false' or not provided, captures the
               page without that step.
 
+          headers: Optional outbound HTTP headers, using the same JSON object or deep-object query
+              format as other scrape endpoints (for example headers[Authorization]=Bearer
+              token). Headers are scoped to the target origin during capture. For domain/page
+              requests, discovery receives no custom headers and only pages on the resolved
+              origin are eligible. Non-empty headers bypass screenshot caching and return an
+              in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+              headers.
+
           max_age_ms: Return a cached screenshot if a prior screenshot for the same parameters exists
               and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when
               omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
@@ -3843,6 +3872,7 @@ async def screenshot(
                         "domain": domain,
                         "full_screenshot": full_screenshot,
                         "handle_cookie_popup": handle_cookie_popup,
+                        "headers": headers,
                         "max_age_ms": max_age_ms,
                         "page": page,
                         "scroll_offset": scroll_offset,
@@ -5884,6 +5914,7 @@ async def web_scrape_screenshot(
         | Omit = omit,
         full_screenshot: Literal["true", "false"] | Omit = omit,
         handle_cookie_popup: bool | Omit = omit,
+        headers: Dict[str, str] | Omit = omit,
         max_age_ms: Optional[int] | Omit = omit,
         scroll_offset: Optional[int] | Omit = omit,
         tags: SequenceNotStr[str] | Omit = omit,
@@ -5927,6 +5958,14 @@ async def web_scrape_screenshot(
               dismiss cookie banner before capture. If 'false' or not provided, captures the
               page without that step.
 
+          headers: Optional outbound HTTP headers, using the same JSON object or deep-object query
+              format as other scrape endpoints (for example headers[Authorization]=Bearer
+              token). Headers are scoped to the target origin during capture. For domain/page
+              requests, discovery receives no custom headers and only pages on the resolved
+              origin are eligible. Non-empty headers bypass screenshot caching and return an
+              in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+              headers.
+
           max_age_ms: Return a cached screenshot if a prior screenshot for the same parameters exists
               and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when
               omitted. Max is 30 days (2592000000 ms). Set to 0 to always capture fresh.
@@ -5982,6 +6021,7 @@ async def web_scrape_screenshot(
                         "country": country,
                         "full_screenshot": full_screenshot,
                         "handle_cookie_popup": handle_cookie_popup,
+                        "headers": headers,
                         "max_age_ms": max_age_ms,
                         "scroll_offset": scroll_offset,
                         "tags": tags,

src/context/dev/types/web_screenshot_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Dict, Optional
 from typing_extensions import Literal, Required, Annotated, TypedDict
 
 from .._types import SequenceNotStr
@@ -266,6 +266,17 @@ class WebScreenshotParams(TypedDict, total=False):
     captures the page without that step.
     """
 
+    headers: Dict[str, str]
+    """
+    Optional outbound HTTP headers, using the same JSON object or deep-object query
+    format as other scrape endpoints (for example headers[Authorization]=Bearer
+    token). Headers are scoped to the target origin during capture. For domain/page
+    requests, discovery receives no custom headers and only pages on the resolved
+    origin are eligible. Non-empty headers bypass screenshot caching and return an
+    in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+    headers.
+    """
+
     max_age_ms: Annotated[Optional[int], PropertyInfo(alias="maxAgeMs")]
     """
     Return a cached screenshot if a prior screenshot for the same parameters exists

src/context/dev/types/web_screenshot_response.py

@@ -74,8 +74,8 @@ class WebScreenshotResponse(BaseModel):
 
     screenshot: Optional[str] = None
     """
-    Public image URL for standard requests, or an in-memory data URL when ZDR is
-    enabled.
+    Public image URL for standard requests, or an in-memory data URL when ZDR or
+    non-empty custom headers are supplied.
     """
 
     screenshot_type: Optional[Literal["viewport", "fullPage"]] = FieldInfo(alias="screenshotType", default=None)

src/context/dev/types/web_web_scrape_screenshot_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Dict, Optional
 from typing_extensions import Literal, Required, Annotated, TypedDict
 
 from .._types import SequenceNotStr
@@ -254,6 +254,17 @@ class WebWebScrapeScreenshotParams(TypedDict, total=False):
     captures the page without that step.
     """
 
+    headers: Dict[str, str]
+    """
+    Optional outbound HTTP headers, using the same JSON object or deep-object query
+    format as other scrape endpoints (for example headers[Authorization]=Bearer
+    token). Headers are scoped to the target origin during capture. For domain/page
+    requests, discovery receives no custom headers and only pages on the resolved
+    origin are eligible. Non-empty headers bypass screenshot caching and return an
+    in-memory data URL; no screenshot is uploaded. Empty objects behave like omitted
+    headers.
+    """
+
     max_age_ms: Annotated[Optional[int], PropertyInfo(alias="maxAgeMs")]
     """
     Return a cached screenshot if a prior screenshot for the same parameters exists

src/context/dev/types/web_web_scrape_screenshot_response.py

@@ -55,8 +55,8 @@ class WebWebScrapeScreenshotResponse(BaseModel):
 
     screenshot: str
     """
-    Public image URL for standard requests, or an in-memory data URL when ZDR is
-    enabled.
+    Public image URL for standard requests, or an in-memory data URL when ZDR or
+    non-empty custom headers are supplied.
     """
 
     url: str

tests/api_resources/test_web.py

@@ -332,6 +332,7 @@ def test_method_screenshot_with_all_params(self, client: ContextDev) -> None:
             domain="xxx",
             full_screenshot="true",
             handle_cookie_popup=True,
+            headers={"foo": "J!"},
             max_age_ms=0,
             page="login",
             scroll_offset=0,
@@ -790,6 +791,7 @@ def test_method_web_scrape_screenshot_with_all_params(self, client: ContextDev)
             country="de",
             full_screenshot="true",
             handle_cookie_popup=True,
+            headers={"foo": "J!"},
             max_age_ms=0,
             scroll_offset=0,
             tags=["production", "team-alpha"],
@@ -1192,6 +1194,7 @@ async def test_method_screenshot_with_all_params(self, async_client: AsyncContex
             domain="xxx",
             full_screenshot="true",
             handle_cookie_popup=True,
+            headers={"foo": "J!"},
             max_age_ms=0,
             page="login",
             scroll_offset=0,
@@ -1650,6 +1653,7 @@ async def test_method_web_scrape_screenshot_with_all_params(self, async_client:
             country="de",
             full_screenshot="true",
             handle_cookie_popup=True,
+            headers={"foo": "J!"},
             max_age_ms=0,
             scroll_offset=0,
             tags=["production", "team-alpha"],