Product and API guide

Render a document

What this endpoint does

One call turns a template and your data into a finished file. The document is produced while you wait and the answer carries a download address; nothing has to be polled. For long documents or bulk work, the queued endpoint does the same job in the background.

Send the template code and your data, get the document back. The download URL in the response is relative to the base address and is fetched with the same API key.

Request 
curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "en",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

The format field takes "pdf" or "docx". Numeric values still work for existing clients: 1 is PDF, 2 is DOCX. Responses return the format as a number.

A purpose of production draws on your quota. While you are trying a template out, send editor-test: that output never touches the quota and uses the unpublished draft revision.

The whole round trip

This is the answer to the call above, and the call that fetches the file. The status is 202: the request was accepted and the document is ready.

Response 
HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}
cURL 
curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

What usually goes wrong

  • Render answers 202, not 200. A client that treats anything other than 200 as a failure reports success as an error.
  • purpose decides two things at once: production uses the published version and consumes quota, editor-test uses the unpublished draft and consumes none. Testing with production is the most expensive way to try a template out.
  • 422 is not a server fault. The body lists every field the template wanted under errors, so the fix is in the data you sent, not in a retry.
  • 402 means the monthly page quota is spent. The X-PDFgine-Quota-Remaining header tells you before you get there.
  • downloadUrl is relative to the API address. Storing it as an absolute URL breaks the day the address changes; store the documentId and build the address.
Response →