Getting your API key

The /v1/render endpoint requires a Pro-plan API key. Free accounts use the web builder at the dashboard instead — there's no API key on the Free plan.

Once you're on Pro (upgrade here), open the API Access panel on your dashboard and click Generate API key. The raw key (starts with df_) is shown exactly once — only its hash is stored server-side, so if you lose it, click Regenerate API key to issue a new one. Regenerating immediately revokes the old key, so update anywhere it's in use before you do.

Authentication

Send your key as a bearer token on every request to /v1/render:

Authorization: Bearer df_your_api_key_here

A missing header returns 401. A revoked or malformed key also returns 401 — DocuForge deliberately doesn't distinguish the two, so a key can't be probed for validity.

Quickstart

Render the standard invoice template with a couple of line items:

curl https://your-docuforge-host/v1/render \
  -H "Authorization: Bearer df_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_inv_98231",
    "data": {
      "invoice_number": "INV-2026-001",
      "client_name": "Acme Corp",
      "company_name": "Your Company Ltd.",
      "brand_color": "#4F46E5",
      "line_items": [
        { "desc": "Consulting", "qty": 4, "price": 150.00 }
      ]
    }
  }' \
  --output invoice.pdf

const res = await fetch("https://your-docuforge-host/v1/render", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DOCUFORGE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "tpl_inv_98231",
    data: {
      invoice_number: "INV-2026-001",
      client_name: "Acme Corp",
      line_items: [{ desc: "Consulting", qty: 4, price: 150.0 }],
    },
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error);
}

const pdfBytes = Buffer.from(await res.arrayBuffer());

A successful response is the raw PDF bytes, with Content-Type: application/pdf. Two extra headers come along for observability: X-Render-Time-Ms (server-side render time) and X-Render-Engine: rust-core.

POST /v1/render

The core endpoint: hydrates a template with JSON data and returns a PDF. Requires API key authentication. No monthly cap and no watermark on Pro — those only apply to the free web builder.

Request body

Invoice data fields

These are the fields the built-in standard invoice template (tpl_inv_98231) reads out of data. A custom template only sees whatever fields you put in data, plus the three DocuForge always injects (brand_color, watermark, payment_block).

Both the QR code and the wire transfer amount always encode the sum of line_items (qty × price), the beneficiary name from company_name, and a remittance reference of Invoice <invoice_number> — not whatever string you passed as amount_due, since that field is display-only and could drift from the real total.

Templates

Templates are HTML/CSS with Jinja-style placeholders ({{ field }}, {% for %}, {% if %}), rendered through the same engine as the built-in invoice. All three endpoints require your API key, same as /v1/render.

Errors

Errors are JSON: { "error": "human-readable message" }, with a status code that tells you what kind of problem it was.

Rate limits & quotas

What's not built yet

options.async, queue-backed rendering, and object storage (S3/R2) for large batch jobs are on the roadmap but not implemented — setting async: true today returns a clear 400 rather than silently ignoring it. Every render is currently synchronous: the PDF comes back in the same response.