URL to PDF API for AI Agents

An AI agent generates a PDF from a URL by sending an authenticated request to a URL to PDF API for AI agents, setting type=pdf, and saving the binary response as a file artifact. With ScreenshotAPI the agent renders any public or authorized page — or its own generated HTML — in real Chrome and gets back a true PDF with selectable text and working links, no local browser or Chromium install required. This guide covers when to choose PDF over an image, the exact requests, a ready-to-use tool schema, and the guardrails that keep autonomous loops safe.

When to use URL-to-PDF

Reach for type=pdf when the agent's deliverable must survive outside the chat as a portable, printable document:

• Reports and dashboard exports that a human will read, file, or forward.
• Invoices, receipts, and statements generated from order or billing data.
• QA, compliance, and audit evidence where a timestamped, self-contained record matters.
• Shareable customer-facing documents like summaries, quotes, or confirmations.
• File artifacts that need to persist in storage, an email attachment, or a ticket — not get pasted back into a prompt as binary.

Prefer an image instead when you only need a visual snapshot for inline review, a thumbnail, or pixel comparison — see the sibling guide on the URL to image API for AI agents. Choose browser automation when the agent must log in, click, fill forms, or step through an interactive flow before the document exists; a stateless capture API cannot drive multi-step interactions.

URL to PDF request

A URL-to-PDF capture is a single authenticated GET. Pass type=pdf and write the binary body straight to a .pdf file.

bash
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

You can also authenticate with a bearer token: -H "Authorization: Bearer sk_live_your_key_here".

JavaScript

javascript
const params = new URLSearchParams({
  url: 'https://example.com/report',
  type: 'pdf',
  fullPage: 'true',
  waitUntil: 'networkidle0'
});

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

if (!response.ok) {
  throw new Error(await response.text());
}

// Save as an artifact, not an inline payload.
await Bun.write('report.pdf', await response.arrayBuffer());

Python

python
import os
import requests

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

with open("report.pdf", "wb") as f:
    f.write(response.content)

HTML to PDF

When the agent generated the document itself — an invoice, a summary, a report built from data — send the markup directly with a POST and type=pdf. The HTML renders in real Chrome, so CSS, web fonts, and page layout all apply.

bash
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 style=\"font-family: sans-serif\"><h1>Incident Summary</h1><p>No active incidents in the last 24 hours.</p></article>",
    "type": "pdf"
  }' \
  --output summary.pdf

The same call from a JavaScript agent:

javascript
const response = await fetch('https://screenshotapi.to/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': process.env.SCREENSHOTAPI_KEY
  },
  body: JSON.stringify({
    html: '<article><h1>Invoice #1042</h1><p>Total due: $480.00</p></article>',
    type: 'pdf'
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

await Bun.write('invoice.pdf', await response.arrayBuffer());

Note: html is accepted only on POST. URL-to-PDF works on GET. Keep generated HTML self-contained with inline CSS so output stays deterministic across runs.

Recommended tool schema

Expose a single, narrow tool to your agent framework. Keeping the surface small makes the model's choices predictable and easy to audit.

json
{
  "name": "generate_pdf",
  "description": "Render a public/authorized URL or agent-generated HTML into a real PDF (selectable text, working links). Use for reports, invoices, receipts, and audit evidence.",
  "parameters": {
    "url": "Absolute public or authorized URL (omit when using html)",
    "html": "Self-contained HTML document (omit when using url; requires POST)",
    "fullPage": "Capture the full scrollable page (boolean)",
    "width": "Viewport width in pixels, 1-1920",
    "waitUntil": "load, domcontentloaded, networkidle0, or networkidle2",
    "waitForSelector": "CSS selector that must appear before rendering",
    "delay": "Extra wait in ms after load, 0-30000",
    "colorScheme": "light or dark"
  }
}

Point GPT Actions and other OpenAPI-compatible tool builders at /openapi.json. Point coding assistants at /llms-full.txt for the full agent-readable documentation corpus.

Reading the response (agent DX)

The body is the binary PDF. The response headers carry signals an agent can use to self-limit and report:

Errors are structured JSON, not the PDF body. A 400 (bad input) and 402 (out of credits) return { error, message }. A 500 returns { error, message, fix }, where fix is a suggested remediation the agent can act on or surface:

json
{
  "error": "render_failed",
  "message": "The page did not finish loading before the timeout.",
  "fix": "Increase delay or set waitUntil=networkidle0 and retry once."
}

Always persist the PDF as a file artifact (a path, blob URL, or attachment). Never base64-encode the binary back into the conversation — it wastes context and corrupts easily.

PDF workflow guardrails

• Artifacts, not binaries. Save the PDF to storage or attach it; do not embed the raw bytes in prompts.
• Cap captures per loop. Set a hard maximum number of PDFs an autonomous run may generate.
• Wait for async data. Use waitUntil=networkidle0 or waitForSelector so dashboards and data-driven pages are fully rendered before capture.
• Public or authorized URLs only. The agent must have permission to render the target.
• Block private targets. Reject localhost, private networks, cloud metadata endpoints, internal services, and paywalled content before making the call.

Real PDF vs image-in-PDF

ScreenshotAPI produces a genuine PDF document, not a screenshot pasted onto a page. This matters for searchability, accessibility, and file size.

If you only need a visual, request type=png/webp instead — a real image is smaller and simpler than a rasterized PDF.

Use it from your stack

• MCP — install the ScreenshotAPI MCP server and the agent gets a generate_webpage_pdf tool for URL- and HTML-to-PDF exports with no glue code.
• OpenAPI — import /openapi.json into GPT Actions, Composio, Pipedream, or Zapier.
• Frameworks — wrap the generate_pdf schema above as a tool in LangChain, the Vercel AI SDK, CrewAI, or your own loop.

For deeper integration patterns, see the AI-agent guide and the PDF screenshot guide.

Related guides

• URL to Image API for AI Agents
• HTML to Image API for AI Agents
• PDF Generation use case
• AI Agent Integrations
• Screenshot API Reference