curlshot
Requires curl and a CurlShot API key; free tier: 100 screenshots/month. Sends URLs or supplied HTML/Markdown to curlshot.com to create screenshots, PDFs, or scrolling videos. Paid plans and setup: htt
screenshot
web-capture
pdf
html-to-image
browser
api
SKILL.mdskills/curlshot/SKILL.md
GitHubCurlShot screenshots
Overview
CurlShot renders a web page in a real browser and returns it as an image (PNG, JPEG, WebP), a PDF, or a video of the page scrolling (MP4, WebM, GIF). One HTTP request does it: GET https://curlshot.com/api/v1/screenshot?url=…, or a POST with a JSON body for your own HTML or Markdown.
Prerequisites
curlon the machine and network access tohttps://curlshot.com.- A CurlShot access key in
CURLSHOT_API_KEY. If it is not set, ask the user for it. A free key comes from https://curlshot.com/register: 100 screenshots a month, no card needed. Paid plans start at $19 a month (https://curlshot.com/pricing). - Never print the key, paste it into a file in the repository, or put it in a link you show the user. Send it in the
X-Access-Keyheader (anAuthorization: Bearer <key>header or anaccess_keyquery parameter also work). - Only public pages work out of the box. Local and private network addresses (localhost, 192.168.x.x, ...) are refused: for a local page, send its HTML instead (see step 4).
Instructions
Check that
CURLSHOT_API_KEYis set (test -n "$CURLSHOT_API_KEY") without echoing its value.Take the screenshot with a GET request:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \ -H "X-Access-Key: $CURLSHOT_API_KEY" \ --data-urlencode "url=https://example.com" \ -d format=png \ -D headers.txt \ --output screenshot.png-Gwith--data-urlencodekeeps the page address correctly encoded.Add options as one more
-d name=valueeach (GET) or as fields in a POST JSON body:Want Option Whole page, top to bottom full_page=truePhone or tablet view viewport_device=<preset>(list: https://curlshot.com/docs/devices.md)Window size viewport_width=1440,viewport_height=900Retina sharpness device_scale_factor=2Dark theme dark_mode=trueOne element only selector=<css selector>Output format format=png/jpeg/webp/pdf/mp4/webm/gifHide cookie banners and ads block_cookie_banners=true,block_ads=trueWait for content wait_until=networkidle,delay=2,wait_for_selector=<css selector>Reuse a stored copy for free cache=trueA misspelled option is rejected with
invalid_optionsand a hint, never ignored. Every option: https://curlshot.com/docs/options.mdTo render your own HTML or Markdown (or a local page), POST JSON:
curl -sS -X POST "https://curlshot.com/api/v1/screenshot" \ -H "X-Access-Key: $CURLSHOT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"html": "<h1>Hello</h1>", "format": "png", "viewport_width": 1200, "viewport_height": 630}' \ --output card.pngUse
"markdown": "..."instead ofhtmlto render Markdown as a styled page, and"format": "pdf"for a PDF.Check the result before you use it (see Output), then tell the user where the file is.
Output
- Success: HTTP
200with aContent-Typeofimage/*,video/*orapplication/pdf. The body is the file, saved by--output. - Failure: HTTP
400or higher withContent-Type: application/json. Do not keep that file as an image; read it as an error (see Error Handling). - Useful response headers:
X-Quota-RemainingandX-Quota-Reset(screenshots left this period),X-RateLimit-Remaining,X-Concurrency-Remaining,X-Cache(cache hit or miss), andX-Reference-Id(quote it when contacting support). - Billing: one successful render counts as one screenshot, whatever its size. Failed renders and cache hits are free.
Error Handling
An error body looks like this:
{
"error_code": "invalid_options",
"error_message": "fullpage: is not a known option; did you mean `full_page`?",
"documentation_url": "https://curlshot.com/docs/errors#invalid_options",
"errors": [{ "field": "fullpage", "message": "is not a known option; did you mean `full_page`?" }]
}
Branch on error_code, never on error_message.
| Status | Codes | What to do |
|---|---|---|
400, 413, 422 |
invalid_options, invalid_url, invalid_request, content_too_large, selector_not_found, page_blocked |
Do not retry. Fix the request using errors and the hint. |
401 |
access_key_required, access_key_invalid |
Do not retry. Ask the user to check CURLSHOT_API_KEY. |
402 |
quota_exceeded |
Do not retry. Tell the user the quota is used up and show upgrade_url. |
403 |
host_not_allowed, feature_not_available, email_not_verified |
Do not retry. For a private or local address, send the HTML instead. For a plan feature, show upgrade_url. |
429 |
rate_limited, concurrency_limit, queue_limit, failure_limit |
Wait the seconds in Retry-After, then retry once. |
500, 502, 503, 504 |
internal_error, navigation_failed, timeout, renderer_busy, renderer_unavailable, service_unavailable |
Retry once after a short pause. For timeout, drop wait_until=networkidle (the default is load) or lower delay. |
Every code with its cause and fix: https://curlshot.com/docs/errors.md
Examples
Full-page screenshot of a site on an iPhone, cookie banners hidden:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com" \
-d viewport_device=iphone_15_pro -d full_page=true -d block_cookie_banners=true \
--output mobile.png
A4 PDF of a page:
curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com/invoice" \
-d format=pdf -d pdf_paper_format=a4 \
--output page.pdf
Markdown rendered to a PDF:
curl -sS -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "# Release notes\n\n- Faster renders", "format": "pdf"}' \
--output notes.pdf
Check the status before trusting the file:
status=$(curl -sS -G "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: $CURLSHOT_API_KEY" \
--data-urlencode "url=https://example.com" \
-o shot.png -w '%{http_code}')
[ "$status" = 200 ] || { cat shot.png; rm shot.png; }
Resources
- Docs: https://curlshot.com/docs
- Getting started: https://curlshot.com/docs/getting-started.md
- All options: https://curlshot.com/docs/options.md
- Device presets: https://curlshot.com/docs/devices.md
- Errors: https://curlshot.com/docs/errors.md
- OpenAPI description: https://curlshot.com/openapi.json
- Everything in one file: https://curlshot.com/llms-full.txt
- Pricing: https://curlshot.com/pricing
- MCP alternative: agents with MCP support can use the hosted server
https://curlshot.com/api/mcp(streamable HTTP,Authorization: Bearer <key>) with the toolstake_screenshotandlist_devices. Setup per client is in this repository's README.