Network Options

Customize network requests with custom headers, cookies, authentication, and more.

Full Configuration

{
  "network": {
    "headers": {
      "X-Custom-Header": "value",
      "Accept-Language": "en-US,en;q=0.9"
    },
    "cookies": [
      {
        "name": "session",
        "value": "abc123",
        "domain": "example.com",
        "path": "/",
        "secure": true,
        "http_only": true,
        "same_site": "Lax",
        "expires": 1705600000
      }
    ],
    "auth": {
      "type": "basic",
      "username": "user",
      "password": "pass"
    },
    "bypass_csp": false
  }
}

Parameters

Parameter	Type	Default	Description
`headers`	object	—	Custom HTTP headers
`cookies`	array	—	Cookies to set before navigation
`auth`	object	—	HTTP authentication
`bypass_csp`	boolean	`false`	Bypass Content Security Policy

Custom Headers

Add custom HTTP headers to requests for the target origin:

{
  "network": {
    "headers": {
      "X-Custom-Header": "my-value",
      "Accept-Language": "fr-FR,fr;q=0.9"
    }
  }
}

Common use cases: - Authorization tokens - Accept-Language for localization - Custom API keys - Cache control

Custom headers go only to the target origin: the origin of url, or of html_base_url for html input. Scripts, images, frames and APIs on other origins never receive them. With html input and no html_base_url, no request receives them. To set Accept-Language for every origin, use browser.locale instead.

Header names are validated; an invalid name is rejected. Host and hop-by-hop headers (such as Connection, Content-Length, Transfer-Encoding, Upgrade and Keep-Alive) are dropped.

Cookies

Set cookies before page load:

{
  "network": {
    "cookies": [
      {
        "name": "auth_token",
        "value": "eyJhbGciOiJIUzI1NiIs...",
        "domain": "example.com"
      }
    ]
  }
}

Property	Type	Required	Description
`name`	string	Yes	Cookie name
`value`	string	Yes	Cookie value
`domain`	string	Yes	Domain for the cookie
`path`	string	No	Path (default: `/`)
`secure`	boolean	No	HTTPS only
`http_only`	boolean	No	HTTP only (no JS access)
`same_site`	string	No	`Strict`, `Lax`, or `None`
`expires`	integer	No	Expiration (Unix timestamp)

The API also accepts httpOnly and sameSite (camelCase, as Puppeteer and Playwright write them) for http_only and same_site. If you send both forms, the snake_case value is used.

Session Authentication

{
  "network": {
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123xyz",
        "domain": "app.example.com",
        "path": "/",
        "secure": true,
        "http_only": true
      }
    ]
  }
}

HTTP Authentication

Basic Auth

{
  "network": {
    "auth": {
      "type": "basic",
      "username": "admin",
      "password": "secret"
    }
  }
}

Bearer Token

{
  "network": {
    "auth": {
      "type": "bearer",
      "token": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

Both auth types are sent only to requests for the target origin (the url origin, or the html_base_url origin for html input), never to third-party scripts, images or APIs the page loads. With html input and no html_base_url, auth is sent to no origin.

Basic auth is sent up front, as an Authorization: Basic header on the first request to the target origin. The site does not need to send a 401 challenge first.

Request Security

Every request the page makes is checked, not only the first navigation: redirects, subresources, frames and script fetches. Requests to private, loopback, link-local and cloud metadata addresses are blocked, and so are IPv6 forms that reach them (NAT64, 6to4 and Teredo). Subresources on ports other than 80 and 443 are blocked too. See blocked.

Proxy Configuration

🚧 Coming Soon

Proxy support is planned for a future release.

Route requests through a proxy:

{
  "network": {
    "proxy": "http://proxy.example.com:8080"
  }
}

With authentication:

{
  "network": {
    "proxy": "http://username:[email protected]:8080"
  }
}

Country Routing

🚧 Coming Soon

Country routing is planned for a future release.

Route requests through a specific country for geo-targeted content:

{
  "network": {
    "country": "gb"
  }
}

Available Countries

Code	Country
`us`	United States
`gb`	United Kingdom
`de`	Germany
`fr`	France
`jp`	Japan
`au`	Australia
`ca`	Canada

Use this for: - Testing geo-restricted content - Capturing localized pricing - Viewing region-specific layouts

Bypass CSP

Bypass Content Security Policy to inject scripts:

{
  "network": {
    "bypass_csp": true
  },
  "page": {
    "scripts": ["console.log('Injected despite CSP')"]
  }
}

Note: Use with caution. Only enable when you need to inject scripts on pages with strict CSP.

Common Patterns

Authenticated Dashboard

{
  "url": "https://dashboard.example.com",
  "network": {
    "cookies": [
      {
        "name": "auth",
        "value": "token123",
        "domain": "dashboard.example.com"
      }
    ]
  }
}

Staging Environment with Basic Auth

{
  "url": "https://staging.example.com",
  "network": {
    "auth": {
      "type": "basic",
      "username": "staging",
      "password": "preview123"
    }
  }
}

Examples

Capture Logged-In State

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "network": {
      "cookies": [
        {
          "name": "session",
          "value": "user_session_token",
          "domain": "app.example.com",
          "secure": true
        }
      ]
    }
  }' \
  --output dashboard.png

API Protected Page

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/docs",
    "network": {
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }' \
  --output api-docs.png