> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookies and headers

> Pass cookies, localStorage values, and custom HTTP headers to capture authenticated or personalized pages.

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.

<Note>
  Cookies, localStorage, and custom headers are advanced features available on the **Pro** plan and above.
</Note>

## Cookies

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

<CodeGroup>
  ```javascript JavaScript SDK theme={null}
  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'
      }
    ]
  });
  ```

  ```bash cURL theme={null}
  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" }
      ]
    }'
  ```
</CodeGroup>

### Cookie object properties

| 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:

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

<Note>
  localStorage values must be strings. Use `JSON.stringify()` for objects.
</Note>

## Custom HTTP headers

Pass additional HTTP headers with the page request:

```bash theme={null}
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.

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

## Common scenarios

### Capturing a logged-in page

```javascript theme={null}
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

```javascript theme={null}
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:

```bash theme={null}
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
```