POST /v1/pdf

Render a PDF from a JSON template. Synchronous; the bytes come back in the response body.

POST /v1/pdf

The render endpoint. Synchronous: the response body is the PDF.

POST /v1/pdf HTTP/1.1
Host: api.gpdf.dev
Authorization: Bearer gpdf_a1b2c3d4...
Content-Type: application/json
Accept: application/pdf

Request body

{
  "template": { /* required — the JSON template */ },
  "data":     { /* optional — interpolated into Go-template fields */ },
  "slug":     "invoice_q1",
  "options": {
    "filename": "invoice.pdf"
  }
}
Field Type Required Notes
template object yes The document tree. See Document schema.
data object no Variable bag; available to {{ ... }} Go-template tags inside template.
slug string no Human label ([A-Za-z0-9._-]{1,64}); empty string is also accepted. Shown in the dashboard logs.
options.filename string no Used for the Content-Disposition header. Defaults to out.pdf.

Body size

The request body, after gzip decoding if Content-Encoding: gzip is set, must be ≤ 8 MiB. A larger payload returns 413 payload_too_large immediately, before any rendering work.

If you need to ship more than 8 MiB of data, reshape into multiple smaller renders or precompute the data server-side.

Successful response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice.pdf"
Content-Length: 12345
X-GPDF-Pages: 3
X-GPDF-Latency-Us: 13872
X-GPDF-Quota-Limit: 10000
X-GPDF-Quota-Remaining: 8749
X-GPDF-Quota-Reset: 2026-05-01T00:00:00Z
X-GPDF-RateLimit-Limit: 40
X-GPDF-RateLimit-Remaining: 37
X-GPDF-RateLimit-Reset: 1714234567
X-Request-Id: req_01HZTV...

<binary PDF>

The body is exactly the PDF bytes. There's no JSON envelope, no base64, no separate fetch.

Full header list: Response headers →.

Output size limits

The generated PDF must fit under your plan's response cap:

Plan Max response
Free 5 MB
Pro 15 MB
Self-host unlimited

Going over returns 413 payload_too_large with code: response_too_large. You can shrink it by:

  • compressing embedded images (the engine doesn't re-encode JPEGs you supply);
  • using vector logos instead of high-DPI raster ones;
  • splitting the document into multiple renders and merging client-side.

Worked examples

Minimal

A single line of text on A4:

curl

curl https://api.gpdf.dev/v1/pdf \
  -H "Authorization: Bearer $GPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "page": { "size": "A4" },
      "body": [{ "text": "Hello, PDF!" }]
    }
  }' \
  --output hello.pdf

Node

const res = await fetch('https://api.gpdf.dev/v1/pdf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPDF_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template: {
      page: { size: 'A4' },
      body: [{ text: 'Hello, PDF!' }]
    }
  })
})
const buf = Buffer.from(await res.arrayBuffer())

Invoice with data

The template is fixed; data carries per-customer values:

{
  "slug": "invoice_q1",
  "template": {
    "page":    { "size": "A4", "margin": "20mm" },
    "header":  [{ "text": "Acme, Inc.", "style": { "color": "#888" } }],
    "footer":  [{ "text": "Page {{.page}} of {{.pages}}", "align": "center" }],
    "body": [
      { "text": "Invoice #{{.id}}", "style": { "fontSize": 18, "weight": "bold" } },
      { "spacer": "4mm" },
      { "text": "Billed to: {{.customer.name}}" },
      { "spacer": "8mm" },
      { "table": {
        "columns": [
          { "span": 7 },
          { "span": 2, "align": "right" },
          { "span": 3, "align": "right" }
        ],
        "header": [
          [{ "text": "Item" }, { "text": "Qty" }, { "text": "Amount" }]
        ],
        "rows": [
          [{ "text": "{{.item.name}}" },
           { "text": "{{.item.qty}}" },
           { "text": "{{.item.amount | printf \"%.2f\"}}" }]
        ]
      }}
    ]
  },
  "data": {
    "id": "INV-001",
    "customer": { "name": "Globex Corp." },
    "item": { "name": "Consulting", "qty": 12, "amount": 2400 }
  }
}

Multi-page report

{
  "template": {
    "page": { "size": "A4" },
    "body": [
      { "text": "Section 1", "style": { "fontSize": 22, "weight": "bold" } },
      { "text": "..." },
      { "page-break": true },
      { "text": "Section 2", "style": { "fontSize": 22, "weight": "bold" } },
      { "text": "..." }
    ]
  }
}

See Multi-page & page breaks →.

CJK

No font upload needed — Noto Sans CJK is bundled. Just write the text:

{
  "template": {
    "page": { "size": "A4" },
    "body": [
      { "text": "请款单 / 请求書 / 인보이스" }
    ]
  }
}

See CJK & fonts →.

Errors

HTTP code When
400 invalid_request Top-level fields wrong: missing template, malformed slug, unknown option.
400 template_error Template parsed but the engine couldn't lay it out (unknown node type, bad spans, etc.). The message includes the offending path.
401 unauthorized Bad or missing key.
402 quota_exceeded Out of monthly credits.
413 payload_too_large Request body over 8 MiB after gzip decoding.
413 response_too_large Rendered PDF exceeded the plan's response cap (Free 5 MB / Pro 15 MB).
429 rate_limited Per-key bucket exhausted. Honour Retry-After.
500 internal_error Bug. The request_id is what we need to track it down.
503 service_unavailable Backend dependency is unhappy. Retry with backoff.

Full guide: Errors →.

Notes

  • No multipart responses. One request → one PDF. If you need multiple PDFs, send multiple requests.
  • Free plan watermark. A pale-grey "Generated by gpdf" stamp (40 pt, mid-page) is added to every page on Free. Removed automatically on Pro and Self-host.
  • Idempotency. The endpoint is not idempotent — every call counts as one render. If you need exactly-once semantics, dedupe on your side using a request-key cache.
  • Streaming. The PDF is written to the response as it's generated, so the time-to-first-byte is independent of the document length. Make sure your client doesn't buffer the whole body in memory if you're rendering 100+ pages.
  • gzip on requests. Requests can use Content-Encoding: gzip; useful when data is large. The 8 MiB body limit applies after decompression. Responses are never gzipped — PDF streams are already DEFLATE-compressed internally so the additional savings are not worth the CPU cost. If you need transport-level compression, configure your CDN / reverse proxy.

Something unclear or missing on this page?