# screenshotbase documentation

> screenshotbase captures pixel-perfect screenshots of any web page and returns them over a simple JSON REST API.

Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.screenshotbase.com

OpenAPI specification: https://screenshotbase.com/docs/openapi.yaml

---

Source: https://screenshotbase.com/docs

# screenshotbase.com API Documentation

Use the screenshotbase.com API to render any website and seamlessly integrate it into your product using one of our many SDKs or other pre-built integrations.

Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://screenshotbase.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://screenshotbase.com/docs/llms.txt) / [llms-full.txt](https://screenshotbase.com/docs/llms-full.txt). There is also a hosted [MCP server](https://screenshotbase.com/docs/mcp) at `https://api.screenshotbase.com/mcp` that AI agents can connect to directly.

## Getting started

To get started, you have to register an API key [here](https://app.screenshotbase.com/register). Then, follow our quickstart guide or continue reading our documentation and integrate screenshotbase.com, using our HTTP API and dedicated client SDKs. Ultimately, [upgrade your plan](https://app.screenshotbase.com/subscription) to access all data & endpoints.

---

Source: https://screenshotbase.com/docs/authentication

# Authentication

You'll need to authenticate your requests to access any of the endpoints in the screenshotbase.com API. In this guide, we'll look at how authentication works. screenshotbase.com offers two ways to authenticate your API requests: API key as `GET` parameter, or via request header.

**MULTIPLE API KEYS**
While our free plan only allows one API key at a time, our [paid plans](https://app.screenshotbase.com/subscription) offer multiple API keys.
By using separate keys for different use cases you can track individual usage and make key rotations affect only certain parts of your application.

## GET query parameter

You can pass your API key along with every request by adding it as a query parameter `apikey`

**WARNING**
This method could expose your API key in access logs and such. Sending the API key via a header parameter as specified below circumvents this problem.

```bash {{ title: 'Example request with authentication via get request' }}
curl "https://api.screenshotbase.com/v1/status?apikey=YOUR-API-KEY"
```

Please don't commit your screenshotbase.com password to GitHub!

## HTTP Header

The recommended way to authenticate with the screenshotbase.com API through a HTTP request header:

```bash {{ title: 'Example request with authentication via header' }}
curl "https://api.screenshotbase.com/v1/status" \
  -H "apikey: YOUR-API-KEY"
```

Always keep your token safe and reset it if you suspect it has been compromised.

## Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the [screenshotbase.com dashboard](https://app.screenshotbase.com/dashboard) and the client library will take care of the rest. All the client libraries use header authentication behind the scenes.

---

Source: https://screenshotbase.com/docs/mcp

'Connect AI agents to the screenshotbase API through our hosted MCP (Model Context Protocol) server.'

# MCP Server

screenshotbase ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required.

```
https://api.screenshotbase.com/mcp
```

The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.screenshotbase.com/register).

## Connect

Using Claude Code:

```bash
claude mcp add --transport http screenshotbase https://api.screenshotbase.com/mcp --header "apikey: YOUR_API_KEY"
```

Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...):

```json
{
  "mcpServers": {
    "screenshotbase": {
      "url": "https://api.screenshotbase.com/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}
```

## Available tools

The tools are generated from the same [OpenAPI specification](https://screenshotbase.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses.

| Tool | Endpoint | Description |
|---|---|---|
| `take` | `GET /v1/take` | Take a screenshot |
| `getStatus` | `GET /v1/status` | Account quota status |

## Quotas and errors

Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed.

---

Source: https://screenshotbase.com/docs/quickstart

# Quickstart

This guide will get you all set up and ready to use the screenshotbase.com API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Before you can make requests to the screenshotbase.com API, you will need to grab your
API key from your dashboard. You find it under [App » Dashboard](https://app.screenshotbase.com/dashboard).

## Choose your client

Before making your first API request, you need to pick which API client you will use. In addition to cURL HTTP requests, screenshotbase.com offers [clients](/sdks) for JavaScript, Python, PHP and many more programming langauges. In the following example, you can see how to install each client.

```bash {{ title: 'cURL' }}
# cURL is most likely already installed on your machine
curl --version
```

```bash {{ language: 'js' }}
# Install the screenshotbase.com JavaScript SDK
npm install @everapi/screenshotbase-js --save
```

```bash {{ language: 'python' }}
# Install the screenshotbase.com Python SDK
pip install screenshotbase
```

```bash {{ language: 'php' }}
# Install the screenshotbase.com PHP SDK
composer require everapi/screenshotbase-php
```

## Making your first API request

After picking your preferred client, you are ready to make your first call to the screenshotbase.com API. Below, you can see how to send a
`GET` request to the `/take` endpoint to render a website.

```bash {{ title: 'cURL' }}
curl -G https://api.screenshotbase.com/v1/take?url=https%3A%2F%2Fbbc.com \
    -H "apikey: YOUR-API-KEY"
```

```js
import Screenshotbase from '@everapi/screenshotbase-js'

const client = new Screenshotbase('YOUR-API-KEY')
client.take('https://bbc.com').then(response => {
    console.log(response);
});

```

```python
import screenshotbase

client = screenshotbase.Client('YOUR-API-KEY')
info = client.take('https://bbc.com')
print(info)
```

```php
    $screenshotbase = new \Screenshotbase\ScreenshotbaseClient('YOUR-API-KEY');
    file_put_contents('/tmp/test.png', $screenshotbase->take('https://bbc.com'));
```

## What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the screenshotbase.com API:

- [Grab your API key from the screenshotbase.com dashboard](#)
- [Learn about the different error messages in screenshotbase.com](/testing)

---

Source: https://screenshotbase.com/docs/rate-limit

# Rate Limit & Quotas

You can use a certain number of requests per month, defined by your plan.

Once you go over this quota, the API returns a `429` HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We enforce a minute rate limit for specific plans. If you exceed this, the API returns a `429` HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume.

Not every request counts
Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.

## Response Headers

We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period.

```json lines
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
```

---

Source: https://screenshotbase.com/docs/sdks

# SDKs

The recommended way to interact with the screenshotbase.com API is by using one of our official SDKs. Today, screenshotbase.com offers fine-tuned JavaScript, Ruby, PHP, Python, and Go libraries to make your life easier and give you the best experience when consuming the API.

---

Source: https://screenshotbase.com/docs/status

# Status Endpoint

The status endpoint returns information about your current quota.

Requests to this endpoint do not count against your quota or rate limit.

---

## Check API Status

This status endpoint returns information about your current quota.

### Response Properties

- **quotas** (object):
Contains information about your request quota.

```bash {{title: 'cURL'}}
curl -G https://api.screenshotbase.com/v1/status \
    -H "apikey: YOUR-API-KEY"
```

```js
import Screenshotbase from '@everapi/screenshotbase-js'

const client = new Screenshotbase('YOUR-API-KEY')

let status = await client.status()
console.log(status)
```

```python
import screenshotbase

client = screenshotbase.Client('YOUR-API-KEY')
result = client.status()
print(result)
```

```php
$client = new \Screenshotbase\ScreenshotbaseClient('YOUR-API-KEY');
$client->status();
```

```json {{title: 'Response'}}
{
    "account_id": 313373133731337,
    "quotas": {
        "month": {
            "total": 300,
            "used": 72,
            "remaining": 229
        },
        "grace": {
            "total": 0,
            "used": 0,
            "remaining": 0
        }
    }
}
```

---

Source: https://screenshotbase.com/docs/status-codes

# Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code `200`.

Before reaching out to support with an error, please be aware that 99% of all
reported errors are, in fact, user errors. Therefore, please carefully check
your code before contacting Protocol support.

---

## Status codes

Here is a list of the different categories of status codes returned by the screenshotbase.com API. Use these to understand if a request was successful.

A 200 status code indicates a successful response.

A 403 status code indicates that you are not allowed to use this endpoint, [please upgrade your plan](https://app.screenshotbase.com/subscription).

A 404 status code indicates that a requested endpoint does not exist.

A validation error has occured.

A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests [please upgrade your plan](https://app.screenshotbase.com/subscription).

A 500 status code indicates a internal server error - let us know: support@screenshotbase.com

---

---

Source: https://screenshotbase.com/docs/take

# Take Endpoint

On this page, we’ll dive into the take endpoint you can use to render a website.

---

## Render a Website

This endpoint lets you render a website.

### Required attributes

- **url** (string):
The URL of the website you want to render.

### Optional attributes

- **format** (string):
The format of the image returned.
Supported: jpg, jpeg, png, gif, webp
Default value is png.

- **quality** (integer):
The quality of the image returned.
Only supported when the format is jpg or jpeg.
Default value is 80.

- **full_page** (boolean):
To take the screenshot of the full page, set full_page=1.
Default value is 0.

- **viewport_width** (integer):
The width of the browser viewport in pixels.
The browser's viewport is the window area where you can see the website.
Default value is 1280.

- **viewport_height** (integer):
The height of the browser viewport in pixels.
The browser's viewport is the window area where you can see the website.
Default value is 800.

- **ip_country_code** (string):
The country code (ISO 3166-1 alpha-2) to use for the IP address when taking the screenshot.
This allows you to simulate requests from different countries.
Must be a valid country code from the supported list.

- **delay** (integer):
The delay in seconds to wait before taking the screenshot.
Minimum value is 0, maximum value is 30.
Default value is 0.

- **timeout** (integer):
The timeout in seconds for the page load.
Minimum value is 5, maximum value is 60.
Default value is 60.

- **wait_until** (string):
Determines when the screenshot should be taken based on page load state.
Supported values:
- `load`: Waits for the load event (entire page and all resources loaded)
- `domcontentloaded`: Waits for HTML document to be loaded and parsed
- `networkidle0`: Waits until there are no active network connections for 500ms
- `networkidle2`: Waits until there are no more than two active network connections for 500ms
Default value is load.

- **block_cookie_banners** (boolean):
Whether to block cookie banners on the page.
Set to 1 to enable, 0 to disable.
Default value is 0.

- **block_ads** (boolean):
Whether to block ads on the page.
Set to 1 to enable, 0 to disable.
Default value is 0.

- **block_chats** (boolean):
Whether to block chat widgets on the page.
Set to 1 to enable, 0 to disable.
Default value is 0.

- **hide_selectors** (array):
An array of CSS selectors to hide on the page.
Elements matching these selectors will be hidden using CSS display: none and visibility: hidden.
You can pass multiple selectors by using the parameter multiple times.
Maximum 255 characters per selector.
Example: `hide_selectors[]=.cookie-banner&hide_selectors[]=#newsletter-popup`

- **styles** (string):
Custom CSS styles to inject into the page before taking the screenshot.
This allows you to modify the page's appearance using any valid CSS.
You should urlencode this value.
Maximum 10,000 characters.
Example: `body { background-color: red !important; }`

```bash {{title: 'cURL'}}
curl -G https://api.screenshotbase.com/v1/take?url=https%3A%2F%2Fbbc.com \
    -H "apikey: YOUR-API-KEY"
```

```js
import Screenshotbase from '@everapi/screenshotbase-js'

let info = await client.take('https://bbc.com')
console.log(info)
```

```python
import screenshotbase

client = screenshotbase.Client('YOUR-API-KEY')
result = client.take('https://bbc.com')
print(result)

```

```php
$screenshotbase = new \Screenshotbase\ScreenshotbaseClient('YOUR-API-KEY')

file_put_contents('/tmp/test.png', $screenshotbase->take('https://bbc.com'));
```