AI Agent Integrations

Overview

ScreenshotAPI gives AI agents and coding assistants a hosted way to capture public or authorized URLs, raw HTML, dashboards, previews, and PDFs — without installing Chromium, maintaining Puppeteer, or running Playwright infrastructure.

It works with any agent through three surfaces:

• REST + OpenAPI — one authenticated GET/POST request. Production-ready today.
• MCP server — four narrow tools for Model Context Protocol clients. See the MCP server guide.
• Agent-readable docs — llms.txt, llms-full.txt, and llms-install.md.

Quick start

Integrate ScreenshotAPI (https://screenshotapi.to) for screenshots and PDFs.

First, read:
- https://screenshotapi.to/llms-full.txt   # full docs + product facts
- https://screenshotapi.to/openapi.json     # machine-readable API contract

Call the REST API with header:  x-api-key: <my key>
Capture public or authorized URLs only — never localhost,
private networks, or cloud metadata endpoints.

curl "https://screenshotapi.to/api/v1/screenshot?url=https://example.com&type=png&fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output screenshot.png

Authentication

Pass your API key with either header:

# Preferred
x-api-key: sk_live_your_key_here

# Also supported
Authorization: Bearer sk_live_your_key_here

Capture a URL

The simplest tool call is an authenticated HTTP request. url is required; type defaults to png.

curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://example.com" \
  -d "type=png" \
  -d "fullPage=true" \
  -H "x-api-key: sk_live_your_key_here" \
  --output screenshot.png

const params = new URLSearchParams({
  url: 'https://example.com',
  type: 'png',
  fullPage: 'true'
})

const res = await fetch(
  `https://screenshotapi.to/api/v1/screenshot?${params}`,
  { headers: { 'x-api-key': process.env.SCREENSHOTAPI_KEY } }
)

if (!res.ok) throw new Error(await res.text())
await Bun.write('screenshot.png', await res.arrayBuffer())

import os, requests

res = requests.get(
    "https://screenshotapi.to/api/v1/screenshot",
    params={"url": "https://example.com", "type": "png", "fullPage": "true"},
    headers={"x-api-key": os.environ["SCREENSHOTAPI_KEY"]},
)
res.raise_for_status()

with open("screenshot.png", "wb") as f:
    f.write(res.content)

Render HTML or export PDF

When the agent generates its own HTML, send it with POST (HTML rendering is not available on GET). Use type=pdf for a real PDF with selectable text and working links.

curl "https://screenshotapi.to/api/v1/screenshot" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  --data '{
    "html": "<main style=\"font-family:sans-serif;padding:40px\"><h1>Weekly Report</h1><p>All checks passed.</p></main>",
    "type": "png",
    "width": 1200,
    "height": 630
  }' \
  --output report.png

curl -G "https://screenshotapi.to/api/v1/screenshot" \
  -d "url=https://example.com/report" \
  -d "type=pdf" \
  -d "waitUntil=networkidle0" \
  -H "x-api-key: sk_live_your_key_here" \
  --output report.pdf

curl "https://screenshotapi.to/api/v1/screenshot" \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: sk_live_your_key_here" \
  --data '{
    "html": "<article><h1>Incident Summary</h1><p>No active incidents.</p></article>",
    "type": "pdf"
  }' \
  --output summary.pdf

Choose your integration

Recommended tool schema

When exposing ScreenshotAPI to an agent framework, keep the tool narrow and action-oriented so the model picks the right capture path:

{
  "name": "capture_url_screenshot",
  "description": "Capture a public or authorized URL as a PNG, JPEG, WebP image, or PDF. Does not click, log in, submit forms, or bypass access controls.",
  "parameters": {
    "url": "Absolute public or authorized URL (http/https)",
    "type": "png, jpeg, webp, or pdf",
    "fullPage": "Capture the full scrollable page (boolean)",
    "width": "Viewport width 1-1920",
    "waitUntil": "load, domcontentloaded, networkidle0, or networkidle2",
    "waitForSelector": "Optional CSS selector that must appear before capture"
  }
}

The MCP server already exposes these as capture_webpage_screenshot, capture_html_screenshot, generate_webpage_pdf, and capture_mobile_screenshot — see the MCP guide.

Reading the response

A successful request returns the binary image or PDF. Response headers give an agent everything it needs to self-regulate:

Errors return JSON. A 400 (invalid options) or 402 (insufficient quota) has { error, message }. A 500 (capture failed) also includes a fix field with a remediation hint:

const res = await fetch(url, { headers: { 'x-api-key': key } })

if (!res.ok) {
  const { error, message, fix } = await res.json()
  // fix often says: try waitUntil=networkidle0, or stealthMode=true
  throw new Error(`${error}: ${message}${fix ? ` — ${fix}` : ''}`)
}

console.log('credits left:', res.headers.get('x-credits-remaining'))

Safety & boundaries

Good fit

• Screenshots of public or authorized URLs.
• Rendering raw HTML to an image or PDF.
• Visual evidence before or after a change.
• Hosted capture instead of running Puppeteer or Playwright.

Not a fit

• Interactive browser control, form submission, or multi-step login.
• Targeting localhost, private networks, cloud metadata, or internal services.
• Bypassing paywalls, account access, or consent.
• Unbounded loops — set a max capture count and use cacheTtl for repeated URLs.

Machine-readable resources

Next steps

• Set up the MCP server for Claude, Cursor, and Codex.
• Review the full Screenshot API reference.
• See the AI agents overview for per-client setup.