Cookies and headers

Some pages require authentication or specific session data to render correctly. Screenshotly lets you pass cookies, localStorage values, and custom HTTP headers with your capture requests.

Cookies, localStorage, and custom headers are advanced features available on the Pro plan and above.

Cookies

Pass an array of cookie objects to set before the page loads. Each cookie follows the standard format:

const screenshot = await client.capture({
  url: 'https://app.example.com/dashboard',
  cookies: [
    {
      name: 'session_id',
      value: 'your_session_token',
      domain: '.example.com'
    },
    {
      name: 'user_pref',
      value: 'dark_mode',
      domain: '.example.com'
    }
  ]
});

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "options": {
      "response_type": "json"
    },
    "cookies": [
      { "name": "session_id", "value": "your_session_token", "domain": ".example.com" }
    ]
  }'

Property	Type	Required	Description
`name`	string	Yes	Cookie name
`value`	string	Yes	Cookie value
`domain`	string	Yes	Domain the cookie belongs to
`path`	string	No	Cookie path (defaults to `/`)
`httpOnly`	boolean	No	HTTP-only flag
`secure`	boolean	No	Secure flag

localStorage

Set key-value pairs in the page’s localStorage before capture:

const screenshot = await client.capture({
  url: 'https://app.example.com/settings',
  localStorage: {
    'authToken': 'bearer-token-here',
    'userPreferences': '{"theme":"dark","language":"en"}'
  }
});

localStorage values must be strings. Use JSON.stringify() for objects.

Custom HTTP headers

Pass additional HTTP headers with the page request:

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api-docs.example.com",
    "headers": {
      "Authorization": "Bearer your-token",
      "X-Custom-Header": "custom-value"
    }
  }'

This is useful for capturing pages behind HTTP-based authentication or pages that render differently based on request headers.

Cookies and custom headers can contain sensitive data. Only send credentials to domains you control. Never log or expose these values.

Common scenarios

Capturing a logged-in page

const screenshot = await client.capture({
  url: 'https://app.example.com/profile',
  cookies: [
    { name: 'session', value: 'active-session-token', domain: '.example.com' }
  ],
  delay: 2000 // wait for authenticated content to load
});

Capturing a page with user preferences

const screenshot = await client.capture({
  url: 'https://example.com',
  localStorage: {
    'theme': 'dark',
    'consentGiven': 'true' // dismiss cookie banner
  }
});

Alternative: Use built-in blockers

For common annoyances like cookie banners and chat widgets, you can use the built-in blocking options instead of cookies:

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "block_cookie_banners": true,
      "block_chats": true,
      "block_ads": true
    }
  }' \
  --output clean-screenshot.png

Getting started

Capture options

Advanced

Integrations

Account

Cookies

localStorage

Custom HTTP headers

Common scenarios

Capturing a logged-in page

Capturing a page with user preferences

Alternative: Use built-in blockers

​Cookies

​Cookie object properties

​localStorage

​Custom HTTP headers

​Common scenarios

​Capturing a logged-in page

​Capturing a page with user preferences

​Alternative: Use built-in blockers

Cookies

Cookie object properties

localStorage

Custom HTTP headers

Common scenarios

Capturing a logged-in page

Capturing a page with user preferences

Alternative: Use built-in blockers