> ## 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.

# API Reference

> Complete API reference for the Screenshothis screenshot service

Generate high-quality website screenshots with a simple REST interface. You get fast, reliable screenshot generation with extensive customization options and built-in security features designed for production use.

<Card title="OpenAPI Specification" icon="code" href="https://api.screenshothis.com/openapi">
  View the complete OpenAPI 3.1 specification for automatic client generation
</Card>

## Getting started quickly

### Base URL

Make all API requests to our production server:

```
https://api.screenshothis.com
```

### Authentication

Authenticate using API keys passed as query parameters. You'll create your API key in the [dashboard](https://screenshothis.com/keys).

**API key security**

Your API keys use domain whitelisting for security—you can safely commit them to version control. Keys only work on domains you've whitelisted in your dashboard.

**Authentication examples**

Add your API key as a query parameter in every request:

<Tabs>
  <Tab title="JavaScript (SDK)">
    ```javascript theme={null}
    import { Screenshothis } from '@screenshothis/sdk';

    const apiKey = 'your_api_key_here';
    const url = 'https://example.com';

    const screenshothis = new Screenshothis();

    const screenshot = await screenshothis.screenshots.take({
      apiKey,
      url,
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.screenshothis.com/v1/screenshots/take?api_key=your_api_key&url=https://example.com"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        'https://api.screenshothis.com/v1/screenshots/take',
        params={
            'api_key': 'your_api_key',
            'url': 'https://example.com'
        }
    )
    ```
  </Tab>
</Tabs>

<Info>
  **Domain whitelisting**: Configure allowed domains in your [dashboard](https://screenshothis.com/keys) to control where your API key can be used. This security model makes it safe to use API keys client-side and commit them to version control.
</Info>

## Usage limits and rate limiting

We enforce fair usage limits to ensure optimal performance for everyone:

| Plan           | Requests per minute | Screenshots per month |
| -------------- | ------------------- | --------------------- |
| **Free**       | 10                  | 100                   |
| **Pro**        | 60                  | 1,000+                |
| **Enterprise** | Custom              | Custom                |

### Monitor your usage

Check your current usage with these response headers:

```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1640995200
```

<Tip>
  Monitor these headers to implement proper retry logic and avoid hitting rate limits
</Tip>

## Error handling

We use standard HTTP status codes and return structured JSON error responses to help you diagnose issues quickly.

### Error response structure

When an error occurs, you receive JSON with detailed information:

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

### HTTP status codes

| Status Code | Meaning               | When it happens                     |
| ----------- | --------------------- | ----------------------------------- |
| `200`       | Success               | Screenshot captured successfully    |
| `400`       | Bad Request           | Invalid parameters or malformed URL |
| `403`       | Forbidden             | Invalid API key or quota exceeded   |
| `429`       | Too Many Requests     | Rate limit exceeded                 |
| `500`       | Internal Server Error | Server-side error occurred          |

### Common error examples

<Tabs>
  <Tab title="Invalid API Key">
    ```json theme={null}
    {
      "error": "Invalid API key provided",
      "requestId": "req_1234567890abcdef"
    }
    ```
  </Tab>

  <Tab title="Quota Exceeded">
    ```json theme={null}
    {
      "error": "Screenshot quota exceeded for current billing period",
      "requestId": "req_abcdef1234567890"
    }
    ```
  </Tab>

  <Tab title="Rate Limited">
    ```json theme={null}
    {
      "error": "Too many requests. Please wait before retrying.",
      "requestId": "req_fedcba0987654321"
    }
    ```
  </Tab>

  <Tab title="Invalid URL">
    ```json theme={null}
    {
      "error": "Invalid URL provided. Must include protocol (http:// or https://)",
      "requestId": "req_0123456789abcdef"
    }
    ```
  </Tab>
</Tabs>

<Warning>
  Always include error handling in your applications. Save the `requestId` from error responses—our support team uses this to help troubleshoot issues faster
</Warning>

## Response formats

### Image responses

You receive screenshot images directly as binary data:

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.screenshothis.com/v1/screenshots/take?api_key=your_api_key&url=https://example.com" \
    -o screenshot.jpeg
  ```
</RequestExample>

<ResponseExample>
  ```
  HTTP/1.1 200 OK
  Content-Type: image/jpeg
  Content-Length: 245760
  Cache-Control: public, max-age=3600

  [Binary image data]
  ```
</ResponseExample>

The `Content-Type` header matches your requested format:

* `image/jpeg` for JPEG format
* `image/png` for PNG format
* `image/webp` for WebP format

## Request limits

We enforce these limits for security and performance:

| Limit Type          | Maximum         | Purpose                            |
| ------------------- | --------------- | ---------------------------------- |
| **Headers**         | 8KB             | Total size of custom HTTP headers  |
| **Cookies**         | 4KB             | Total size of custom cookies       |
| **URL length**      | 2048 characters | Standard browser compatibility     |
| **Request timeout** | 30 seconds      | Maximum screenshot generation time |

<Note>
  These limits support the vast majority of legitimate use cases while preventing abuse
</Note>

## Development tools

<CardGroup cols={2}>
  <Card title="JavaScript SDK" icon="js" href="/sdk/js">
    Official TypeScript SDK with full type safety, error handling, and tree-shaking support
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/screenshothis/screenshothis-js">
    View source code, report issues, or contribute to the JavaScript SDK
  </Card>
</CardGroup>

## Quick start steps

Ready to capture your first screenshot? Follow these steps:

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

  <Step title="Create an API key">
    Generate your API key at [screenshothis.com/keys](https://screenshothis.com/keys) in your dashboard.
  </Step>

  <Step title="Make your first request">
    Use the examples in this documentation to capture your first screenshot.

    <Check>
      Your first screenshot will be ready in under 2 seconds
    </Check>
  </Step>

  <Step title="Explore advanced features">
    Learn about content blocking, device simulation, and custom selectors to enhance your screenshots.
  </Step>
</Steps>

<Tip>
  Start with our [Quickstart Guide](/quickstart) for a complete step-by-step tutorial, then return here for detailed API reference information
</Tip>