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

# Custom Cookies

> Set custom cookies for authenticated screenshots

## Custom Cookies

Set custom cookies to capture screenshots of authenticated pages or specific user states.

## Basic usage

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&customCookies=%5B%7B%22name%22%3A%22session%22%2C%22value%22%3A%22abc123%22%2C%22domain%22%3A%22example.com%22%7D%5D" \
    --output screenshot.png
  ```

  ```typescript typescript theme={null}
  const cookies = [
    {
      name: 'session',
      value: 'abc123',
      domain: 'example.com'
    }
  ];

  const params = new URLSearchParams({
    key: 'YOUR_API_KEY',
    url: 'https://example.com',
    customCookies: JSON.stringify(cookies)
  });

  await fetch(`https://api.domshot.com/shot?${params}`)
    .then(res => res.blob())
    .then(blob => fs.writeFile('screenshot.png', blob));
  ```

  ```php php theme={null}
  $cookies = [
    [
      'name' => 'session',
      'value' => 'abc123',
      'domain' => 'example.com'
    ]
  ];

  $params = [
    'key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'customCookies' => json_encode($cookies)
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.domshot.com/shot?' . http_build_query($params));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
  $result = curl_exec($ch);
  file_put_contents('screenshot.png', $result);
  curl_close($ch);
  ```

  ```go go theme={null}
  package main

  import (
      "encoding/json"
      "net/http"
      "net/url"
  )

  type Cookie struct {
      Name   string `json:"name"`
      Value  string `json:"value"`
      Domain string `json:"domain"`
  }

  func main() {
      cookies := []Cookie{
          {Name: "session", Value: "abc123", Domain: "example.com"},
      }

      params := url.Values{}
      params.Set("key", "YOUR_API_KEY")
      params.Set("url", "https://example.com")

      cookiesJSON, _ := json.Marshal(cookies)
      params.Set("customCookies", string(cookiesJSON))

      resp, _ := http.Get("https://api.domshot.com/shot?" + params.Encode())
      defer resp.Body.Close()

      // Save response to file
  }
  ```
</CodeGroup>

## Cookie object format

```json theme={null}
[
  {
    "name": "session",
    "value": "abc123",
    "domain": "example.com",
    "path": "/",
    "httpOnly": false,
    "secure": true,
    "sameSite": "Lax"
  }
]
```

### Required fields

| Field    | Type   | Description   |
| -------- | ------ | ------------- |
| `name`   | string | Cookie name   |
| `value`  | string | Cookie value  |
| `domain` | string | Cookie domain |

### Optional fields

| Field      | Type    | Description                                 |
| ---------- | ------- | ------------------------------------------- |
| `path`     | string  | Cookie path (default: `/`)                  |
| `httpOnly` | boolean | HTTP-only flag (default: `false`)           |
| `secure`   | boolean | Secure flag (default: `false`)              |
| `sameSite` | string  | SameSite policy: `Strict`, `Lax`, or `None` |

## Multiple cookies

<CodeGroup dropdown>
  ```bash bash theme={null}
  curl "https://api.domshot.com/shot?key=YOUR_API_KEY&url=https://example.com&customCookies=%5B%7B%22name%22%3A%22session%22%2C%22value%22%3A%22abc123%22%7D%2C%7B%22name%22%3A%22theme%22%2C%22value%22%3A%22dark%22%7D%5D" \
    --output screenshot.png
  ```

  ```typescript typescript theme={null}
  const cookies = [
    {
      name: 'session',
      value: 'abc123',
      domain: 'example.com'
    },
    {
      name: 'theme',
      value: 'dark',
      domain: 'example.com'
    }
  ];

  const params = new URLSearchParams({
    key: 'YOUR_API_KEY',
    url: 'https://example.com',
    customCookies: JSON.stringify(cookies)
  });

  await fetch(`https://api.domshot.com/shot?${params}`)
    .then(res => res.blob())
    .then(blob => fs.writeFile('screenshot.png', blob));
  ```

  ```php php theme={null}
  $cookies = [
    ['name' => 'session', 'value' => 'abc123', 'domain' => 'example.com'],
    ['name' => 'theme', 'value' => 'dark', 'domain' => 'example.com']
  ];

  $params = [
    'key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'customCookies' => json_encode($cookies)
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://api.domshot.com/shot?' . http_build_query($params));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
  $result = curl_exec($ch);
  file_put_contents('screenshot.png', $result);
  curl_close($ch);
  ```

  ```go go theme={null}
  package main

  import (
      "encoding/json"
      "net/http"
      "net/url"
  )

  type Cookie struct {
      Name   string `json:"name"`
      Value  string `json:"value"`
      Domain string `json:"domain"`
  }

  func main() {
      cookies := []Cookie{
          {Name: "session", Value: "abc123", Domain: "example.com"},
          {Name: "theme", Value: "dark", Domain: "example.com"},
      }

      params := url.Values{}
      params.Set("key", "YOUR_API_KEY")
      params.Set("url", "https://example.com")

      cookiesJSON, _ := json.Marshal(cookies)
      params.Set("customCookies", string(cookiesJSON))

      resp, _ := http.Get("https://api.domshot.com/shot?" + params.Encode())
      defer resp.Body.Close()

      // Save response to file
  }
  ```
</CodeGroup>

<Warning>
  Never expose sensitive authentication data in URLs that might be logged. Consider using environment variables for sensitive data.
</Warning>

## Parameters

| Parameter       | Type   | Description                  |
| --------------- | ------ | ---------------------------- |
| `customCookies` | string | JSON array of cookie objects |

## See also

* [Custom Headers](/guides/advanced/headers) - Set custom HTTP headers
* [Custom User Agent](/guides/advanced/user-agent) - Set custom user agent