curlshot

CurlShot Screenshots

Overview

CurlShot renders a page in a real browser and returns the result 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=… for a public URL, or a POST with a JSON body for raw HTML or Markdown. Agents with MCP support can use the hosted server https://curlshot.com/api/mcp (tools take_screenshot, list_devices) instead of curl.

When to Use

• Use when the user wants a screenshot or full-page capture of a public URL.
• Use when the user wants a page as it looks on a phone or tablet preset, at a given window size, or in dark mode.
• Use when the user wants a page saved as a PDF or as a scrolling video.
• Use when generated HTML or Markdown (a social card, a report, a local page) must be rendered to an image or PDF.
• Do not use for localhost or private network URLs by address: the API refuses them. Send the page's HTML instead.

Process

1. Check the key without printing it: test -n "$CURLSHOT_API_KEY". If it is missing, ask the user for one. A free key (100 screenshots a month, no card) comes from https://curlshot.com/register.

2. Capture a URL. Send the key in the X-Access-Key header, never in a link you show the user:

   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 full_page=true -d block_cookie_banners=true \
     -o shot.png -w '%{http_code}\n'
   

3. Add options as extra -d name=value pairs: viewport_device=<preset> (list: https://curlshot.com/docs/devices.md), viewport_width/viewport_height, dark_mode=true, selector=<css>, format=jpeg|webp|pdf|mp4|webm|gif, block_ads=true, wait_until=networkidle, delay=<seconds>, cache=true. Every option: https://curlshot.com/docs/options.md

4. Render raw HTML or Markdown with a POST:

   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}' \
     -o card.png