API Documentation
Everything you need to integrate ShotAPI into your project.
Base URL: https://api.shotapi.dev
JSON API
Authentication
All API requests require an X-API-Key header. Get your key from the dashboard.
bash
curl -X POST https://api.shotapi.dev/v1/screenshot \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'
POST
/v1/screenshot
Capture a screenshot of any URL. Returns the image binary directly, or a PDF for format: "pdf".
| Parameter | Type | Default | Description |
|---|---|---|---|
url |
string | required | URL to capture |
width |
int | 1280 | Viewport width in pixels |
height |
int | 720 | Viewport height in pixels |
full_page |
bool | false | Capture the full scrollable page |
format |
string | png | png jpeg webp or pdf |
quality |
int | 80 | JPEG/WebP quality (1-100) |
delay |
float | 0 | Wait seconds before capture |
mockup |
string | null | browser iphone macbook ipad |
| Advanced Parameters Requires Pro or Max plan | |||
selector |
string | null | CSS selector for element screenshot Pro |
device_scale_factor |
float | null | Retina/HiDPI scale (e.g. 2, 3) Pro |
dark_mode |
bool | false | Force dark color scheme Pro |
custom_css |
string | null | Inject custom CSS before capture Pro |
custom_js |
string | null | Execute JavaScript after page load Pro |
headers |
object | null | Custom HTTP headers Pro |
user_agent |
string | null | Custom User-Agent string Pro |
cookies |
array | null | Inject cookies [{name, value, url}] Pro |
wait_for_selector |
string | null | Wait for element before capture Pro |
click_selector |
string | null | Click element before capture Pro |
hide_selectors |
array | null | Hide elements by CSS selector Pro |
geolocation |
object | null | {latitude, longitude} emulation Pro |
timezone |
string | null | Timezone ID (e.g. America/New_York) Pro |
block_ads |
bool | false | Block ads and trackers Max |
Example Request
bash
curl -X POST https://api.shotapi.dev/v1/screenshot \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"width": 1440,
"height": 900,
"format": "webp",
"quality": 90,
"full_page": true,
"dark_mode": true,
"device_scale_factor": 2
}' \
--output screenshot.webp
POST
/v1/render
Render HTML + CSS to an image. Perfect for social cards, invoices, certificates, and dynamic OG images.
| Parameter | Type | Default | Description |
|---|---|---|---|
html |
string | required | HTML content to render |
css |
string | null | CSS stylesheet to inject |
width |
int | 800 | Viewport width in pixels |
height |
int | 600 | Viewport height in pixels |
format |
string | png | png jpeg or webp |
| Advanced Parameters | |||
device_scale_factor |
float | null | Retina/HiDPI scale (e.g. 2, 3) Pro |
custom_js |
string | null | Execute JavaScript after load Pro |
Example Request
bash
curl -X POST https://api.shotapi.dev/v1/render \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"html": "<h1 style=\"color:red\">Hello World</h1>",
"css": "body { background: white; padding: 40px; }",
"width": 800,
"height": 600,
"format": "png"
}' \
--output render.png
POST
/v1/metadata
Extract metadata, Open Graph tags, and detected technologies from any URL. Optionally extract page content as Markdown.
| Parameter | Type | Default | Description |
|---|---|---|---|
url |
string | required | URL to extract metadata from |
extract_markdown |
bool | false | Extract page content as Markdown Pro |
Example Request
bash
curl -X POST https://api.shotapi.dev/v1/metadata \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://github.com", "extract_markdown": true}'Example Response
json
{
"title": "GitHub",
"description": "Where the world builds software.",
"og": { "title": "GitHub", "image": "..." },
"technologies": ["React", "Node.js"],
"markdown": "# GitHub\nWhere the world builds software..."
}
POST
/v1/batch
Screenshot multiple URLs in parallel. Results are saved to storage and returned as an array of file URLs.
| Parameter | Type | Default | Description |
|---|---|---|---|
urls |
array | required | Array of URLs to capture |
options |
object | {} | Shared screenshot options (same as /v1/screenshot params) |
Example Request
bash
curl -X POST https://api.shotapi.dev/v1/batch \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://google.com", "https://github.com"],
"options": {"width": 1280, "format": "png"}
}'
POST
/v1/diff
Visual diff between two URLs. Returns a diff image highlighting changes, with an X-Diff-Percentage response header indicating how much changed.
| Parameter | Type | Default | Description |
|---|---|---|---|
url_a |
string | required | First URL to compare |
url_b |
string | required | Second URL to compare |
Example Request
bash
curl -X POST https://api.shotapi.dev/v1/diff \
-H "X-API-Key: sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{"url_a": "https://example.com", "url_b": "https://example.org"}' \
--output diff.pngError Responses
All errors return JSON with a detail field describing the issue.
| Status | Meaning | Description |
|---|---|---|
400 |
Bad Request | Invalid or missing parameters |
401 |
Unauthorized | Missing or invalid API key |
403 |
Forbidden | Feature requires a higher plan (Pro or Max) |
429 |
Rate Limited | Too many requests. Check X-RateLimit-* headers |
500 |
Server Error | Internal error. Retry or contact support |
Error Response Format
json
{
"detail": "Missing required parameter: url"
}