# PDFEx

> PDFEx is a PDF generation and template-design service. You can create templates, render
> them to PDF, and print documents on demand — over a REST API or over MCP. Templates use
> one of two engines: `html` (Handlebars + headless Chromium, recommended for agents) or
> `pdfme` (coordinate-based, millimetre units).

## Read this first — no API key required

- [Full agent guide](https://pdfex.io/llms-full.txt): the complete contract — endpoints, both
  engines, field reference, the design loop, and the per-host install matrix.
- [Contract as JSON](https://pdfex.io/api/schema): engines, field types, units, page sizes and
  the advertised preview limits. The same payload an authenticated caller gets from
  `/api/capabilities`, minus their own plan limits.
- [Host install matrix](https://pdfex.io/.well-known/mcp-hosts.json): machine-readable — the
  endpoint, the transport, the auth header, and how to configure 18
  different agent hosts.
- [Rendered documentation](https://pdfex.io/docs): the same material for humans.

## Connect over MCP

```
POST https://pdfex.io/mcp
Streamable HTTP, stateless — GET and DELETE return 405 by design
Authorization: Bearer pdfex_...
```

One key covers both surfaces: the REST API and MCP share the same credential path.
See `https://pdfex.io/.well-known/mcp-hosts.json` for the exact config for your host.

## Getting a key

Create or revoke keys at https://pdfex.io/secure/keys. Keys are per-account; a free tier
exists. Set it as `PDFEX_API_KEY` in your environment where your host supports that.

## The five calls that matter (with a key)

1. `GET  /api/capabilities` — what you are allowed to write, plus your plan limits.
2. `GET  /api/templates/samples` — adapt a real invoice/certificate rather than inventing JSON.
3. `POST /api/templates/validate` — cheap check; never renders, never saves.
4. `POST /api/templates/preview` — renders and returns an **image** you can look at.
5. `POST /api/pdf/token` then `GET /api/pdf/:token` — print a real PDF.

Look at the preview before you save. That is the whole discipline.