API reference
Use a dashboard API key (dr_live_…) for server-to-server calls.
Authentication
Authorization: Bearer dr_live_<your_key>
Create keys in the dashboard under API Keys. Keys are scoped to your account only.
POST /api/v1/render
Render a single PDF or PNG from a saved template ID or inline HTML.
Optional body fields:
page—paper(A4|Letter|Legal|A5),landscape,margin(top/right/bottom/leftCSS lengths),headerHtml,footerHtml(PDF),width/height/fullPage(PNG)postProcess—watermark: { text, opacity? },pageNumbers: { position?, fontSize? }(PDF)fileName,callbackUrl(HTTPS webhook on completion)
curl -X POST "$APP_URL/api/v1/render" \
-H "Authorization: Bearer dr_live_..." \
-H "Content-Type: application/json" \
-d '{
"templateId": 1,
"data": { "name": "Ada" },
"format": "pdf",
"page": { "paper": "A4", "margin": { "top": "12mm" } },
"callbackUrl": "https://yourapp.com/webhooks/render"
}'GET /api/v1/jobs/:id
Poll job status, download URL, cache/billing flags, and errors for a render you own.
curl "$APP_URL/api/v1/jobs/42" \ -H "Authorization: Bearer dr_live_..."
POST /api/v1/batch
Render many documents in one request; returns a ZIP or merged PDF when complete.
items is an array of per-row data objects (not wrapped in data). Set merge: true (PDF only) to also get one combined PDF; fileNameField picks a ZIP member name from each row.
curl -X POST "$APP_URL/api/v1/batch" \
-H "Authorization: Bearer dr_live_..." \
-H "Content-Type: application/json" \
-d '{
"templateId": 1,
"format": "pdf",
"merge": true,
"fileNameField": "name",
"items": [
{ "name": "Ada" },
{ "name": "Grace" }
]
}'Template syntax
{{variable}}— interpolate JSON field{{#each items}}…{{/each}}— loop over an array{{#if flag}}…{{/if}}— conditional block{{money amount}}— currency formatting{{date ts}}— date formatting
Render webhooks
When a job finishes, doc-render POSTs to your callbackUrl with header:
Doc-Render-Signature: t=<unix>,v1=<hmac-sha256 hex>
Verify with your callback secret from the dashboard:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifyDocRenderWebhook(secret, rawBody, signatureHeader) {
const parts = signatureHeader.split(',').map(p => p.trim());
let t = '';
let v1 = '';
for (const part of parts) {
const [key, value] = part.split('=', 2);
if (key === 't' && value) t = value;
if (key === 'v1' && value) v1 = value;
}
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(v1);
if (a.length !== b.length) return false;
return timingSafeEqual(a, b);
}Error codes
| HTTP | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 422 | Invalid template, sandbox block, or render limit |
| 429 | Quota exceeded — buy credits or wait for monthly free reset |
| 503 | Render queue full — retry with backoff |