Bring your own AI

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 agentPaste into Claude, Cursor, ChatGPT, etc.

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 sub-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 sub-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.

# 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:

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.

# 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 and pass it to your agent as an environment variable or config value. Simplest approach for agents you control.

# 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.

# 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.

# 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 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.

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:

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

MCP server — 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 — Web UI walkthrough, API keys, your first template
API Reference — Full endpoint documentation
Generate — VS Code, Obsidian, library templates, embedded AI chat