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 whendatais 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.
Related
- Document schema → — the
templategrammar. - Templates guide → — worked examples by use case.
- Response headers → — every header we set.
Something unclear or missing on this page?