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:

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

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

HTTPMeaning
401Missing or invalid API key
422Invalid template, sandbox block, or render limit
429Quota exceeded — buy credits or wait for monthly free reset
503Render queue full — retry with backoff