CurlShot 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

• curl on the machine and network access to https://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-Key header (an Authorization: Bearer <key> header or an access_key query 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

1. Check that CURLSHOT_API_KEY is set (test -n "$CURLSHOT_API_KEY") without echoing its value.

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

   -G with --data-urlencode keeps the page address correctly encoded.

3. Add options as one more -d name=value each (GET) or as fields in a POST JSON body:

   Want	Option
   Whole page, top to bottom	full_page=true
   Phone or tablet view	viewport_device=<preset> (list: https://curlshot.com/docs/devices.md)
   Window size	viewport_width=1440, viewport_height=900
   Retina sharpness	device_scale_factor=2
   Dark theme	dark_mode=true
   One element only	selector=<css selector>
   Output format	format=png / jpeg / webp / pdf / mp4 / webm / gif
   Hide cookie banners and ads	block_cookie_banners=true, block_ads=true
   Wait for content	wait_until=networkidle, delay=2, wait_for_selector=<css selector>
   Reuse a stored copy for free	cache=true

   A misspelled option is rejected with invalid_options and a hint, never ignored. Every option: https://curlshot.com/docs/options.md

4. To 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.png

   Use "markdown": "..." instead of html to render Markdown as a styled page, and "format": "pdf" for a PDF.

5. Check the result before you use it (see Output), then tell the user where the file is.

Output

• Success: HTTP 200 with a Content-Type of image/*, video/* or application/pdf. The body is the file, saved by --output.
• Failure: HTTP 400 or higher with Content-Type: application/json. Do not keep that file as an image; read it as an error (see Error Handling).
• Useful response headers: X-Quota-Remaining and X-Quota-Reset (screenshots left this period), X-RateLimit-Remaining, X-Concurrency-Remaining, X-Cache (cache hit or miss), and X-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.

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 tools take_screenshot and list_devices. Setup per client is in this repository's README.