Documents

Generate a document

POST/templates/{id}/generations

Creates an immutable document: the template's saved version with values applied. Answers 201 with the document, including its Markdown, its page URL and where its PDF stands. The PDF starts rendering on our servers the moment the document exists; it is usually ready within seconds.

Parameters

Name	Type	Description
`id`required	uuid	The template's id.
`values`	object	Placeholder key to value; group key to an array of instance objects. See Filling placeholders.
`title`	string	A name for the document. Default: the template's title followed by its number.

Request

curl -X POST https://usepaperclerk.com/api/v1/templates/4d1f0c2e-7b3a-4c1e-9d2f-1a2b3c4d5e6f/generations \
  -H "Authorization: Bearer pc_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice — Maple & Fern, September",
    "values": {
      "client_name": "Maple & Fern Ltd.",
      "payment_terms": "Net 15",
      "due_date": "10/15/2026",
      "line_items": [
        { "item": "Brand identity system", "quantity": "1", "amount": "4800" },
        { "item": "Brand guidelines document", "quantity": "1", "amount": "1200" }
      ]
    }
  }'

Response

JSON

HTTP/1.1 201 Created
Location: https://usepaperclerk.com/app/generated/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b

{
  "id": "9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b",
  "template_id": "4d1f0c2e-7b3a-4c1e-9d2f-1a2b3c4d5e6f",
  "title": "Invoice — Maple & Fern, September",
  "generation_number": 13,
  "source": "api",
  "source_version": 3,
  "created_at": "2026-09-12T14:02:11.480Z",
  "markdown": "# Invoice — Maple & Fern, September\n\nInvoice INV-0013 for Maple & Fern Ltd. …",
  "html": "<div class=\"doc-page\" …>…</div>",
  "html_truncated": false,
  "url": "https://usepaperclerk.com/app/generated/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b",
  "pdf_status": "pending",
  "pdf_url": "https://usepaperclerk.com/api/v1/generations/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b/pdf"
}

The Location header carries the document's page URL.
If the same request arrives again within 10 minutes, the answer is the document already generated: HTTP 200 with replayed: true instead of 201.
pdf_status starts at pending and becomes ready once the render lands; pdf_url is the PDF endpoint below.