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

# Quickstart

> Master the Screenshothis API in under 5 minutes

# Get your first screenshot

Capture your first screenshot and explore advanced features. You'll go from zero to production-ready integration in under 5 minutes.

<Steps>
  <Step title="Create your account">
    Sign up for a free account at [screenshothis.com](https://screenshothis.com/register) to get 100 free screenshots per month.

    <Check>
      You'll be redirected to your dashboard immediately after registration
    </Check>
  </Step>

  <Step title="Generate your API key">
    Navigate to [API Keys](https://screenshothis.com/keys) in your dashboard and create your first API key.

    <Info>
      Your API keys use domain whitelisting for security—you can safely commit them to version control. Configure allowed domains in your dashboard to control where your key works.
    </Info>
  </Step>

  <Step title="Make your first request">
    Test your API key with a simple screenshot request using any method below.
  </Step>
</Steps>

## Your first screenshot

<Tabs>
  <Tab title="cURL">
    The quickest way to test the API:

    ```bash theme={null}
    curl -X GET "https://api.screenshothis.com/v1/screenshots/take?api_key=ss_test_1234567890abcdef&url=https://github.com" \
      -o screenshot.jpeg
    ```

    <Check>Your screenshot saves as `screenshot.jpeg` in the current directory</Check>
  </Tab>

  <Tab title="JavaScript">
    Perfect for web applications and Node.js:

    ```bash theme={null}
    npm install @screenshothis/sdk
    ```

    ```typescript theme={null}
    import { Screenshothis } from "@screenshothis/sdk";

    const screenshothis = new Screenshothis();

    async function takeScreenshot() {
      try {
        const imageData = await screenshothis.screenshots.take({
          apiKey: "ss_test_1234567890abcdef",
          url: "https://github.com"
        });

        // Save to file (Node.js)
        const fs = require('fs');
        fs.writeFileSync('screenshot.jpeg', Buffer.from(imageData));

        console.log('Screenshot saved successfully!');
      } catch (error) {
        console.error('Screenshot failed:', error.message);
      }
    }

    takeScreenshot();
    ```

    <Card title="Complete SDK Guide" icon="arrow-right" href="/sdk/js">
      For comprehensive documentation including error handling, tree-shaking, React/Vue examples, and all available options
    </Card>
  </Tab>

  <Tab title="Python">
    Ideal for data science and backend services:

    ```python theme={null}
    import requests

    try:
        response = requests.get(
            'https://api.screenshothis.com/v1/screenshots/take',
            params={
                'api_key': 'ss_test_1234567890abcdef',
                'url': 'https://github.com'
            }
        )

        response.raise_for_status()  # Raise an exception for bad responses

        with open('screenshot.jpeg', 'wb') as f:
            f.write(response.content)

        print('Screenshot saved successfully!')

    except requests.exceptions.RequestException as e:
        print(f'Screenshot failed: {e}')
    ```

    <Check>You'll see "Screenshot saved successfully!" when the image saves</Check>
  </Tab>

  <Tab title="PHP">
    Great for WordPress and Laravel integrations:

    ```php theme={null}
    <?php
    try {
        $params = http_build_query([
            'api_key' => 'ss_test_1234567890abcdef',
            'url' => 'https://github.com'
        ]);

        $url = 'https://api.screenshothis.com/v1/screenshots/take?' . $params;
        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'timeout' => 30
            ]
        ]);

        $screenshot = file_get_contents($url, false, $context);

        if ($screenshot === false) {
            throw new Exception('Failed to capture screenshot');
        }

        file_put_contents('screenshot.jpeg', $screenshot);
        echo 'Screenshot saved successfully!';

    } catch (Exception $e) {
        echo 'Screenshot failed: ' . $e->getMessage();
    }
    ?>
    ```
  </Tab>
</Tabs>

## Customize your screenshots

Control format, size, and behavior with these parameters:

<CodeGroup>
  ```bash Enhanced cURL theme={null}
  curl -X GET "https://api.screenshothis.com/v1/screenshots/take" \
    -G \
    -d "api_key=ss_test_1234567890abcdef" \
    -d "url=https://github.com" \
    -d "format=webp" \
    -d "quality=90" \
    -d "width=1920" \
    -d "height=1080" \
    -d "block_ads=true" \
    -d "block_cookie_banners=true" \
    -d "prefers_color_scheme=dark" \
    -d "is_cached=true" \
    -d "cache_ttl=7200" \
    -o screenshot.webp
  ```

  ```typescript Enhanced JavaScript theme={null}
  import { Screenshothis } from "@screenshothis/sdk";

  const screenshothis = new Screenshothis();

  async function takeCustomScreenshot() {
    try {
      const result = await screenshothis.screenshots.take({
        apiKey: "ss_test_1234567890abcdef",
        url: "https://github.com",
        format: "webp",
        quality: 90,
        width: 1920,
        height: 1080,
        blockAds: true,
        blockCookieBanners: true,
        prefersColorScheme: "dark",
        prefersReducedMotion: "reduce",
        isCached: true,
        cacheTtl: 7200
      });

      // Save to file
      const fs = require('fs');
      fs.writeFileSync('screenshot.webp', Buffer.from(result));

      console.log('Custom screenshot saved!');
    } catch (error) {
      console.error('Failed to capture:', error.message);
    }
  }
  ```

  ```python Enhanced Python theme={null}
  import requests
  import json

  try:
      # Custom headers for authenticated content
      custom_headers = json.dumps({
          "Authorization": "Bearer your-token",
          "User-Preference": "dark-mode"
      })

      response = requests.get(
          'https://api.screenshothis.com/v1/screenshots/take',
          params={
              'api_key': 'ss_test_1234567890abcdef',
              'url': 'https://github.com',
              'format': 'webp',
              'quality': '90',
              'width': '1920',
              'height': '1080',
              'block_ads': 'true',
              'block_cookie_banners': 'true',
              'prefers_color_scheme': 'dark',
              'headers': custom_headers,
              'is_cached': 'true',
              'cache_ttl': '7200'
          },
          timeout=30
      )

      response.raise_for_status()

      with open('screenshot.webp', 'wb') as f:
          f.write(response.content)

      print('Custom screenshot saved!')

  except requests.exceptions.RequestException as e:
      print(f'Failed to capture: {e}')
  ```
</CodeGroup>

### Mobile device simulation

See how your website appears on mobile devices:

<CodeGroup>
  ```bash Mobile cURL theme={null}
  curl -X GET "https://api.screenshothis.com/v1/screenshots/take" \
    -G \
    -d "api_key=ss_test_1234567890abcdef" \
    -d "url=https://github.com" \
    -d "is_mobile=true" \
    -d "width=390" \
    -d "height=844" \
    -d "device_scale_factor=3" \
    -d "has_touch=true" \
    -d "format=webp" \
    -d "quality=85" \
    -o mobile-screenshot.webp
  ```

  ```typescript Mobile JavaScript theme={null}
  const mobileScreenshot = await screenshothis.screenshots.take({
    apiKey: "ss_test_1234567890abcdef",
    url: "https://github.com",
    isMobile: true,
    width: 390,
    height: 844,
    deviceScaleFactor: 3,
    hasTouch: true,
    format: "webp",
    quality: 85,
    userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15"
  });
  ```

  ```python Mobile Python theme={null}
  mobile_params = {
      'api_key': 'ss_test_1234567890abcdef',
      'url': 'https://github.com',
      'is_mobile': 'true',
      'width': '390',
      'height': '844',
      'device_scale_factor': '3',
      'has_touch': 'true',
      'format': 'webp',
      'quality': '85'
  }

  response = requests.get(
      'https://api.screenshothis.com/v1/screenshots/take',
      params=mobile_params,
      timeout=30
  )
  ```
</CodeGroup>

## API parameters

Customize your screenshots with these parameters:

### Required parameters

<ParamField query="api_key" type="string" required>
  Your API key from the dashboard. Uses domain whitelisting for security—safe to commit to version control.
</ParamField>

<ParamField query="url" type="string" required>
  The website URL to screenshot. Must be a valid URL including protocol (http\:// or https\://).
</ParamField>

### Viewport and device settings

<ParamField query="width" type="integer" default="1920">
  Viewport width in pixels. Range: 100-3840.
</ParamField>

<ParamField query="height" type="integer" default="1080">
  Viewport height in pixels. Range: 100-2160.
</ParamField>

<ParamField query="is_mobile" type="boolean" default="false">
  Simulate mobile device viewport and user agent.
</ParamField>

<ParamField query="is_landscape" type="boolean" default="false">
  Set device orientation to landscape when using mobile simulation.
</ParamField>

<ParamField query="has_touch" type="boolean" default="false">
  Enable touch input simulation for the device.
</ParamField>

<ParamField query="device_scale_factor" type="number" default="1">
  Device pixel ratio for high-DPI displays. Common values: 1, 1.5, 2, 3.
</ParamField>

### Image output settings

<ParamField query="format" type="string" default="jpeg">
  Image format. Options: `jpeg`, `png`, `webp`.
</ParamField>

<ParamField query="quality" type="integer" default="80">
  Image quality for JPEG and WebP formats. Range: 20-100.
</ParamField>

<ParamField query="selector" type="string">
  CSS selector to screenshot a specific element instead of the full page.
</ParamField>

### Content filtering

<ParamField query="block_ads" type="boolean" default="false">
  Block advertisements and tracking scripts for cleaner screenshots.
</ParamField>

<ParamField query="block_cookie_banners" type="boolean" default="false">
  Automatically dismiss cookie consent banners and privacy notices.
</ParamField>

<ParamField query="block_trackers" type="boolean" default="false">
  Block all trackers and third-party scripts.
</ParamField>

### Accessibility and preferences

<ParamField query="prefers_color_scheme" type="string" default="light">
  Set color scheme preference. Options: `light`, `dark`.
</ParamField>

<ParamField query="prefers_reduced_motion" type="string" default="no-preference">
  Set motion preference for animations. Options: `no-preference`, `reduce`.
</ParamField>

### Caching settings

<ParamField query="is_cached" type="boolean" default="false">
  Enable caching for this screenshot to improve performance on repeated requests.
</ParamField>

<ParamField query="cache_ttl" type="integer" default="3600">
  Cache time-to-live in seconds when caching is enabled. Range: 3600-31622400 (1 hour to 1 year).
</ParamField>

<ParamField query="cache_key" type="string">
  Custom cache key for grouping related screenshots. Use with `is_cached=true`.
</ParamField>

### Content filtering (NEW)

<ParamField query="block_requests" type="string">
  Block specific URL patterns during page load. One pattern per line, supports wildcards.

  ```text theme={null}
  *.doubleclick.net
  *.googletagmanager.com
  */analytics/*
  ```
</ParamField>

<ParamField query="block_resources" type="array">
  Block specific resource types from loading. Available types: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `prefetch`, `eventsource`, `websocket`, `manifest`, `signedexchange`, `ping`, `cspviolationreport`, `preflight`, `other`.

  ```bash theme={null}
  # Block scripts and stylesheets for faster loading
  -d "block_resources=script,stylesheet"
  ```
</ParamField>

### Advanced browser settings

<ParamField query="headers" type="string">
  Custom HTTP headers in `Name: Value` format, one per line. Maximum size: 8KB.

  ```text theme={null}
  Authorization: Bearer token
  User-Agent: MyBot/1.0
  X-Custom-Header: value
  ```
</ParamField>

<ParamField query="cookies" type="string">
  Custom cookies using Set-Cookie syntax, one per line. Maximum size: 4KB.

  ```text theme={null}
  session_id=abc123; Domain=example.com; Path=/; Secure
  user_pref=dark_mode; Max-Age=3600
  ```
</ParamField>

<ParamField query="bypass_csp" type="boolean" default="false">
  Bypass Content Security Policy restrictions. Use only when necessary for specific sites.
</ParamField>

<Note>
  **Security and size limits**:

  * Headers: Maximum 8KB total size
  * Cookies: Maximum 4KB total size
  * URL length: Maximum 2048 characters
  * Request timeout: 30 seconds maximum
</Note>

## Response formats

### Image response (default)

You receive the screenshot image directly as binary data:

```bash theme={null}
curl "https://api.screenshothis.com/v1/screenshots/take?api_key=ss_test_1234567890abcdef&url=https://github.com" \
  -o screenshot.jpeg
```

**Content-Type**: `image/jpeg`, `image/png`, or `image/webp` based on your `format` parameter.

### Error responses

When requests fail, you receive a JSON error response:

```json theme={null}
{
  "error": "Invalid API key",
  "requestId": "req_1234567890abcdef"
}
```

Common HTTP status codes:

* `400` - Bad request (invalid parameters)
* `403` - Forbidden (invalid API key or quota exceeded)
* `429` - Too many requests (rate limit exceeded)
* `500` - Internal server error

## Test the API interactively

<Frame caption="Try different parameters without writing code">
  <Card title="API Playground" icon="play" href="https://screenshothis.com/playground">
    Test the API with different URLs and parameters to see results instantly.
  </Card>
</Frame>

### Sample URLs for testing

Try these URLs to see different screenshot results:

* **Modern website**: `https://screenshothis.com`
* **Code repository**: `https://github.com/screenshothis/screenshothis`
* **Documentation**: `https://docs.screenshothis.com`
* **News site**: `https://news.ycombinator.com`

## Real-world examples

<AccordionGroup>
  <Accordion title="Social media previews" icon="share">
    Generate dynamic `og:image` tags for better social media sharing:

    ```typescript theme={null}
    import { Screenshothis } from "@screenshothis/sdk";

    async function generateSocialPreview(blogPostUrl: string, apiKey: string) {
      const screenshothis = new Screenshothis();

      try {
        const imageData = await screenshothis.screenshots.take({
          apiKey,
          url: blogPostUrl,
          width: 1200,
          height: 630,
          format: "jpeg",
          quality: 85
        });

        // Convert to base64 for immediate use
        const base64 = Buffer.from(imageData).toString('base64');
        return `data:image/jpeg;base64,${base64}`;
      } catch (error) {
        console.error('Failed to generate preview:', error.message);
        return null;
      }
    }

    // Usage in your application
    const previewUrl = await generateSocialPreview("https://myblog.com/post", apiKey);
    // Use in HTML: <meta property="og:image" content="data:image/jpeg;base64,..." />
    ```

    <Check>Perfect for Twitter, LinkedIn, and Facebook sharing cards</Check>
  </Accordion>

  <Accordion title="Website thumbnails" icon="image">
    Create thumbnails for link previews, portfolios, or dashboards:

    ```python theme={null}
    import requests
    from PIL import Image
    from io import BytesIO

    def create_thumbnail(website_url, api_key, thumbnail_size=(400, 300)):
        try:
            response = requests.get(
                'https://api.screenshothis.com/v1/screenshots/take',
                params={
                    'api_key': api_key,
                    'url': website_url,
                    'width': '1920',
                    'height': '1080',
                    'format': 'png'
                },
                timeout=30
            )

            response.raise_for_status()

            # Create thumbnail using PIL
            image = Image.open(BytesIO(response.content))
            image.thumbnail(thumbnail_size, Image.Resampling.LANCZOS)

            return image

        except requests.exceptions.RequestException as e:
            print(f'Failed to create thumbnail: {e}')
            return None

    # Usage
    thumbnail = create_thumbnail('https://example.com', 'ss_test_1234567890abcdef')
    if thumbnail:
        thumbnail.save('thumbnail.png')
    ```

    <Tip>Use WebP format for smaller file sizes in web applications</Tip>
  </Accordion>

  <Accordion title="Visual regression testing" icon="bug">
    Capture screenshots for automated testing pipelines:

    ```typescript theme={null}
    import { Screenshothis } from "@screenshothis/sdk";
    import * as fs from 'fs';
    import * as path from 'path';

    class VisualTester {
      private screenshothis: Screenshothis;

      constructor(private apiKey: string) {
        this.screenshothis = new Screenshothis();
      }

      async captureBaseline(url: string, testName: string): Promise<string> {
        try {
          const imageData = await this.screenshothis.screenshots.take({
            apiKey: this.apiKey,
            url,
            width: 1920,
            height: 1080,
            format: "png",
            blockAds: true  // Consistent results
          });

          const filename = `baselines/${testName}.png`;
          fs.writeFileSync(filename, Buffer.from(imageData));

          console.log(`✅ Baseline saved: ${filename}`);
          return filename;

        } catch (error) {
          console.error(`❌ Failed to capture baseline: ${error.message}`);
          throw error;
        }
      }
    }

    // Usage in your test suite
    const tester = new VisualTester('ss_test_1234567890abcdef');
    await tester.captureBaseline('https://myapp.com/component', 'header-component');
    ```

    <Check>Ideal for CI/CD pipelines and automated quality assurance</Check>
  </Accordion>

  <Accordion title="Direct URL rendering" icon="link">
    **The most efficient approach - construct the URL directly:**

    ```typescript theme={null}
    // Build screenshot URLs without making API calls
    function buildScreenshotUrl(
      url: string,
      apiKey: string,
      options: Record<string, string | number | boolean> = {}
    ): string {
      const params = new URLSearchParams({
        api_key: apiKey,
        url: url,
        ...Object.fromEntries(
          Object.entries(options).map(([k, v]) => [k, String(v)])
        )
      });

      return `https://api.screenshothis.com/v1/screenshots/take?${params}`;
    }

    // Usage - instant, no async needed!
    const screenshotUrl = buildScreenshotUrl("https://github.com", "ss_test_1234567890abcdef", {
      format: "png",
      width: 800,
      height: 600,
      block_ads: true
    });

    // Use directly in HTML
    document.getElementById('myImage').src = screenshotUrl;
    // Or in React: <img src={screenshotUrl} alt="Screenshot" />
    ```

    **React component example:**

    ```tsx theme={null}
    interface ScreenshotImageProps {
      url: string;
      apiKey: string;
      width?: number;
      height?: number;
      format?: 'jpeg' | 'png' | 'webp';
    }

    function ScreenshotImage({ url, apiKey, width = 800, height = 600, format = 'webp' }: ScreenshotImageProps) {
      const screenshotUrl = buildScreenshotUrl(url, apiKey, {
        width,
        height,
        format,
        block_ads: true
      });

      return (
        <img
          src={screenshotUrl}
          alt="Screenshot"
          loading="lazy"
          onError={(e) => console.error('Screenshot failed to load')}
        />
      );
    }

    // Usage
    <ScreenshotImage
      url="https://example.com"
      apiKey="ss_test_1234567890abcdef"
      width={1200}
      height={630}
      format="webp"
    />
    ```

    <Check>**Much more efficient!** The browser fetches the image directly - no intermediate processing needed</Check>
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available parameters, response formats, and error handling
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/sdk/js">
    Use our official TypeScript SDK with full type safety and error handling
  </Card>

  <Card title="Self-hosting" icon="server" href="/self-host">
    Run Screenshothis on your own infrastructure for complete control
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="https://api.screenshothis.com/openapi">
    Generate client libraries for any programming language
  </Card>
</CardGroup>