# SnapForge

> Rendering & web-content API for AI agents. Turn any URL or HTML into a
> screenshot (PNG/JPEG), a print-ready PDF, or clean Markdown for LLMs — with a
> single authenticated HTTP request. Native MCP server (works with Claude,
> Cursor, Hermes, OpenClaw and any MCP client). Managed Chromium fleet.
> Base URL: https://snapforge.org

## Authentication

All rendering endpoints require an API key in the `x-api-key` header.
Get a free key (100 one-time renders, no monthly reset) by POSTing your email to
`/signup`, or subscribe for more: Starter (2,000/mo) and Pro (10,000/mo) at
https://snapforge.org/#pricing

## Endpoints

### POST /v1/screenshot
Render a URL or raw HTML to an image.
Headers: `x-api-key: <key>`, `content-type: application/json`
Body (JSON), provide either `url` or `html`:
- `url` (string): public http/https page to capture (private/internal hosts are blocked)
- `html` (string): raw HTML to render instead of a URL (max 2 MB)
- `fullPage` (bool): capture the entire scrollable page (default true; set false for viewport only)
- `width` (int 100–3840, default 1280), `height` (int 100–2160, default 800)
- `scale` (int 1–3, default 1): device pixel ratio for high-DPI
- `format` ("png" | "jpeg", default png), `quality` (1–100, jpeg only)
- `waitUntil` ("load" | "networkidle"), `delay` (ms 0–10000)
Returns: binary image (`image/png` or `image/jpeg`).

Example:
```
curl -X POST https://snapforge.org/v1/screenshot \
  -H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"url":"https://example.com","fullPage":true}' --output shot.png
```

### POST /v1/pdf
Render a URL or raw HTML to a PDF.
Headers and `url`/`html`/`waitUntil`/`delay` as above. Extra body fields:
- `singlePage` (bool): render one continuous page sized to the content height (no A4 pagination)
- `pageFormat` ("A4" default, or Letter/Legal/Tabloid/A0–A6)
- `landscape` (bool), `printBackground` (bool, default true), `margin` (CSS size string, e.g. "1cm")
Returns: `application/pdf`.

Example:
```
curl -X POST https://snapforge.org/v1/pdf \
  -H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"url":"https://example.com","pageFormat":"A4"}' --output page.pdf
```

### POST /v1/markdown
Extract clean Markdown from a page (article extraction + HTML→Markdown) — ideal for feeding web content to an LLM.
Headers: `x-api-key: <key>`, `content-type: application/json`. Body: `url` or `html`.
Returns: `text/markdown`.

Example:
```
curl -X POST https://snapforge.org/v1/markdown \
  -H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
  -d '{"url":"https://example.com"}'
```

### GET /v1/usage
Returns `{ plan, used, quota, month }` for the key in `x-api-key`.

### POST /signup
Body `{ "email": "you@example.com" }` → `{ apiKey, plan: "free", monthlyQuota: 100 }` (free = 100 one-time renders).

## Notes for agents
- One render = one quota unit; a 429 means the quota is exhausted (free = 100 one-time, paid resets monthly).
- Responses include `x-quota-used` / `x-quota-limit` headers.
- Only public http/https targets are allowed (SSRF-protected).
- An official MCP server lets agents call SnapForge as a tool. Local (stdio): `npx snapforge-mcp` with `SNAPFORGE_API_KEY`. Hosted (Streamable HTTP, zero install): `https://snapforge.org/mcp` with your key in the `x-api-key` header.

## Links
- Pricing: https://snapforge.org/#pricing
- Terms: https://snapforge.org/terms
- Privacy: https://snapforge.org/privacy