API docs

Endpoints

Convert body fields

A conversion, end to end

curl -X POST \
  https://webcapture.io/v1/convert \
  -H "Authorization: Bearer wc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/"}'

200 {"id": "cnv_9f2c01ab", "bytes": 34121, "attempts": 1,
    "remaining": 49, "sourceUrl": "https://example.com/", "sourceType": "url",
    "download": "https://webcapture.io/v1/conversions/cnv_9f2c01ab.pdf"}

# Pass ?wait=false to skip the hold and poll instead:
# 202 {"id": "cnv_9f2c01ab", "status": "queued",
#     "poll": "https://webcapture.io/v1/conversions/cnv_9f2c01ab",
#     "download": "https://webcapture.io/v1/conversions/cnv_9f2c01ab.pdf"}

GET the download path with the same key to fetch the PDF. GET /v1/usage for the quota left this month. Poll no faster than about once a second; renders usually finish in seconds, not minutes.

Render HTML your backend already built

For invoices, reports, certificates and receipts, build the HTML from your own data and POST it directly. No public page is needed. This example also resolves /assets/logo.png against the supplied base:

curl -X POST \
  https://webcapture.io/v1/convert \
  -H "Authorization: Bearer wc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"html":"<html><body><img src="/assets/logo.png"><h1>Invoice #1042</h1><p>Total due: 420 USD</p></body></html>","baseUrl":"https://cdn.example.com/"}'

Send exactly one of html or url. Every receipt carries sourceType: "url" | "html", so clients do not need to treat about:blank as a real URL. Without baseUrl, the legacy sourceUrl is about:blank; with it, relative assets and any fetch controls use that admitted public origin.

Errors and what to do

Webhooks

Set a webhookUrl on the key: in the dashboard key form, or in the body of POST /v1/keys. Signed webhooks are a Pro and Scale feature; endpoints must be https (http is accepted only on self-hosted deployments that allow private targets). Completed conversions POST a JSON event to it:

{"version": 1,
 "type": "conversion.completed",
 "conversionId": "cnv_9f2c01ab",
 "apiKeyId": "key_5c1d09ab2e4f6071",
 "sourceUrl": "https://example.com/", "sourceType": "url",
 "pdfBytes": 5327,
 "completedAt": "2026-09-13T09:41:07.000Z"}

Headers: X-WebCapture-Event carries the event type, X-WebCapture-Event-Id echoes the conversion id, X-WebCapture-Attempt counts delivery attempts, and X-WebCapture-Timestamp the unix time in seconds. X-WebCapture-Signature: t=<ts>,v1=<hex> is the HMAC-SHA256 of <ts>.<body> keyed with the key's webhook secret. The secret is shown once, when the webhook is saved. Deliveries retry with exponential backoff and failed ones are re-driven a couple more times over about half an hour before being dropped, so a receiver can see the same event twice: dedupe on conversionId. Endpoints must be https, and redirects are not followed. Failed conversions send no event.

Verify the signature before acting on an event: recompute it over the raw body your endpoint received, with the secret from the dashboard.

import { createHmac, timingSafeEqual } from "node:crypto";

export function webhookVerified(rawBody, sigHeader, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(sigHeader ?? "");
  if (!m) return false;
  const mac = createHmac("sha256", secret).update(`${m[1]}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(m[2], "hex"), Buffer.from(mac, "hex"));
}

Hash the raw request body exactly as received: re-serializing the JSON changes the bytes and the MAC never matches. The X-WebCapture-Timestamp header is inside the MAC, so treat deliveries older than a few minutes as suspect.

For agents (MCP)

webcapture ships a first-party MCP endpoint, so an agent gets PDF rendering as one tool call. The connection facts, all of them:

A minimal client config for MCP clients that speak HTTP connectors (Claude Desktop, Cursor, your own agent):

{
  "mcpServers": {
    "webcapture": {
      "url": "https://webcapture.io/mcp",
      "headers": { "Authorization": "Bearer wc_your_key" }
    }
  }
}

Prefer the terminal? Claude Code takes the same endpoint as one command:

claude mcp add --transport http webcapture https://webcapture.io/mcp \
  --header "Authorization: Bearer wc_your_key"

With the client connected, ordinary prompts do the work:

• "Turn this article into a PDF for our records"
• "Capture this dashboard in dark mode"
• "Hand me this page as Markdown for the notes pipeline"

The tool result carries the finished document as an absolute URL on this origin, so the agent can fetch it without guessing the host:

conversion cnv_9f2c01ab complete (5327 bytes).
Download: https://webcapture.io/v1/conversions/cnv_9f2c01ab.pdf

Keep the API key server-side. The key renders pages on your account, so it never belongs in the browser or in any client-side code. Call webcapture from your own backend and hand users the finished file.

Machine-readable discovery sits next to the endpoint, so an agent can read the facts instead of the docs: the A2A agent card at /.well-known/agent-card.json, the MCP server card at /.well-known/mcp/server-card.json, and the skills index at /.well-known/agent-skills/index.json.

No MCP client? The same capability is the plain REST call in the end-to-end example. This page is also available as one markdown document at /docs.md.

Guides for common jobs

Step-by-step versions of the tasks behind these endpoints: keeping formatting intact, migrating off wkhtmltopdf, and self-hosted versus hosted costs. The price checks measure the field directly: the best-of comparison and the free-tier table price per document, the capability matrix compares feature by feature, and all four engine head-to-heads live on the comparisons index. Prefer a browser to an API call? The free URL to PDF tool converts a page without a key. Automating the call? The automation platform guides carry the same endpoint into eight no-code and agent builders, and the recipe library holds one complete program per task, one language per page. The full list lives on the guides index.

For platform-specific wiring, see n8n, Zapier, Make, Bubble, Clay, FlowMattic, Lovable, or Base44. For an async shell job, the curl polling recipe shows the full ticket lifecycle.