# Bring your own AI

> For AI agents: a documentation index is available at https://makespdf.com/llms.txt — every docs page also has a markdown twin (append .md to the page URL), including this one: https://makespdf.com/docs/ai-setup.md

MakesPDF doesn't ship an AI. It ships a deterministic rendering API and a skill
file that teaches *any* agent — Claude Code, Cursor, ChatGPT, Continue,
Windsurf, or your own — to author PDF templates. Pick your model, pay them for
the reasoning, pay us for the pixels.

> **Quick start — paste this into your agent:** install the skill file
> (https://makespdf.com/skills/pdf-template-author.md) as context, then ask for the document
> you want. The page above this section carries a copy-to-clipboard prompt for
> exactly that.

```text
Use this skill to author PDFs: https://makespdf.com/skills/pdf-template-author.md
```

## How it works

MakesPDF provides a **skill file** that teaches AI assistants how to create PDF
templates using a compact builder DSL. The AI writes a small JavaScript snippet,
the API renders it to a compliant PDF in about a second wall-clock. No design
knowledge required from you or the AI — the DSL encodes professional document
patterns (invoices, receipts, CVs, etc.) as composable functions.

You prompt your AI → AI writes a DSL script → `POST /api/v1/preview` → PDF in
about a second.

The skill file contains the full DSL reference — builder functions, style
properties, document recipes, and the preview API. Once loaded, any AI assistant
can generate templates without needing to understand the underlying PDF
specification.

## Installing the skill

The skill file is plain markdown. Install it however your agent reads project
context — every agent has its own conventions (Claude Code uses
`.claude/skills/`, Cursor uses `.cursor/rules/`, Copilot reads
`.github/copilot-instructions.md`, OpenCode and Codex have their own paths).
Check your tool's documentation.

### Shortcut: the makesPDF CLI

`@makespdf/cli` embeds the skill file and prints it on demand — redirect the
output wherever your agent looks. It also gives your AI assistant deterministic
`validate` and `preview` commands to iterate on templates locally, so the agent
isn't making HTTP calls directly for every change.

```bash
# Ad-hoc — no install needed
npx @makespdf/cli skill > pdf-template-author.md

# Or install globally and sign in once
npm install -g @makespdf/cli
makespdf login                       # browser-based device flow
makespdf skill > pdf-template-author.md
makespdf validate template.js        # pre-flight check, no render
makespdf preview template.js --data data.json -o out.pdf
```

### Any AI coding agent

Download the skill file and register it with your agent as a skill, rule, or
instruction set:

```bash
curl -o pdf-template-author.md \
  https://makespdf.com/skills/pdf-template-author.md
```

Once installed, try: "Create an invoice PDF for Acme Corp with 3 line items."

### ChatGPT, Claude.ai, or any chat interface

Paste the skill file contents as context at the start of your conversation, or
upload it as a file attachment. The AI will then understand the DSL and can
generate templates for you.

```
# View/download the skill file
https://makespdf.com/skills/pdf-template-author.md
```

### Custom AI agents

Include the skill file in your agent's system prompt or tool definitions. Your
agent can then call the preview API directly to render PDFs.

```js
// Fetch the skill at agent startup
const skillFile = await fetch(
  "https://makespdf.com/skills/pdf-template-author.md"
).then(r => r.text());

// Include in your system prompt
const systemPrompt = skillFile + "\n\n" + yourInstructions;
```

## Authentication for agents

Your AI agent needs an API key to call MakesPDF. Two options:

**Option A: Pre-configured API key.** Create an API key in
[Settings → API Keys](https://makespdf.com/settings/api-keys) and pass it to your agent as
an environment variable or config value. Simplest approach for agents you
control.

```bash
# Set as environment variable
export MAKESPDF_API_KEY="mpdf_your_api_key"

# Agent uses it in requests
curl -X POST https://makespdf.com/api/v1/preview \
  -H "Authorization: Bearer $MAKESPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dsl": "const template = doc(...);"}'
```

**Option B: Local development (`MAKESPDF_DEV_TOKEN`).** When you're running the
dev server yourself (or pointing an agent at `http://localhost:8788`) and don't
want to complete the device flow first, set `MAKESPDF_DEV_TOKEN` in
`apps/web/.dev.vars` and send it as a Bearer token. Production rejects this
token regardless of value.

```bash
# Generate a token (one-off)
echo "MAKESPDF_DEV_TOKEN=$(openssl rand -hex 32)" >> apps/web/.dev.vars
pnpm dev   # restart so wrangler picks up the new var

# Use it
export MAKESPDF_DEV_TOKEN="...the value you just generated..."
curl -X POST http://localhost:8788/api/v1/preview \
  -H "Authorization: Bearer $MAKESPDF_DEV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"dsl": "const template = doc(page(col(s(\"Hello\")))); const sampleData = {};"}' \
  -o output.pdf
```

Each accepted bypass is logged with a `[auth]` warn line in the dev console, so
accidental usage is loud. The token is unbilled and renders without a watermark
— same as a paid tier — so you can iterate on layouts without DRAFT stamping.

**Option C: Device authorization flow (zero-config).** For agents that need to
authenticate without a pre-configured key — e.g. a CLI tool or a shared agent
that multiple users run. The agent opens the user's browser, the user approves,
and the agent receives a persistent API key. No secrets to manage.

```bash
# 1. Agent requests a device code
curl -X POST https://makespdf.com/api/v1/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My AI Agent"}'

# Response:
# {
#   "device_code": "abc123",
#   "user_code": "ABCD-1234",
#   "verification_uri_complete": "https://makespdf.com/device?code=ABCD-1234",
#   "expires_in": 600,
#   "interval": 5
# }

# 2. Agent opens the verification URL in the user's browser
# 3. User logs in (if needed) and approves the request
# 4. Agent polls every 5 seconds until approved

curl -X POST https://makespdf.com/api/v1/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "abc123"}'

# On approval:
# { "access_token": "mpdf_...", "token_type": "Bearer" }
```

See the [API Reference](https://makespdf.com/docs/api) for full device flow details
including error handling.

## The preview API

The skill file teaches the AI to output DSL scripts. These are rendered via
`POST /api/v1/preview` — a fast, no-AI endpoint that takes the DSL script and
optional data, and returns a PDF.

```bash
curl -X POST https://makespdf.com/api/v1/preview \
  -H "Authorization: Bearer mpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dsl": "const template = doc({ size: \"A4\", title: \"Invoice\" }, page(col(s(\"Hello World\")))); const sampleData = {};",
    "data": {}
  }' -o output.pdf
```

When the AI generates a DSL script, it also generates `sampleData`. If you don't
pass `data` in the request, the sample data is used automatically — so the AI's
output is immediately renderable without any extra input.

> **Validate first:** Use `POST /api/v1/preview/validate` to check a template for
> structure and accessibility issues before rendering. It's free and fast — a
> good practice for agents that generate templates programmatically.

## Example: end-to-end interaction

After installing the skill, a typical interaction looks like this:

```text
You:   Create an invoice for Acme Corp, 3 items: web design ($2500),
       hosting ($300), domain ($15). Tax 10%.

Agent: I'll create an invoice template and render it.
       [writes DSL script using doc(), table(), totals(), etc.]
       [calls POST /api/v1/preview with the script]
       [saves output.pdf]

       Done! I've created invoice.pdf — a professional invoice
       with your line items, 10% tax, and totals.
```

The AI handles all the layout, styling, and PDF generation. You just describe
what you want in plain language.

## What's next

- [Integrate into your app](https://makespdf.com/docs/integrate) — three copy-paste recipes
  (backend render, hosted MCP, Vercel AI SDK tools) for drop-in AI-built PDF
  templates.
- [MCP server](https://makespdf.com/docs/mcp) — Register makesPDF as a Model Context
  Protocol server in Claude Desktop, Claude Code, Cursor, or any MCP-aware
  client. Gives the AI schema-validated tools instead of prose-about-JSON.
- [Getting Started](https://makespdf.com/docs/getting-started) — Web UI walkthrough, API
  keys, your first template
- [API Reference](https://makespdf.com/docs/api) — Full endpoint documentation
- [Generate](https://makespdf.com/generate) — VS Code, Obsidian, library templates, embedded
  AI chat
