Response · PDFgine

What comes back

Every successful render answers with the same object. Two of its fields are worth keeping: documentId identifies the file for as long as it is retained, and pageCount is what the month is billed by.

Response

{
  "documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
  "jobId": "job_00b96f006b034258b00b650d724d0207",
  "fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 5,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
  "previewUrl": null,
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent",
  "createdAt": "2026-08-28T13:23:32+00:00"
}

A render stays private and its download requires your API key. Use the preview endpoint only when you intentionally need an expiring customer link.

Response headers

Every render response repeats the metering figures in its headers, so you can track the quota without a second call.

`X-PDFgine-Pages`	Page count of this document
`X-PDFgine-Job`	Identifier of the render job
`X-PDFgine-Quota-Remaining`	Pages left after the operation
`X-PDFgine-Metering-Basis`	Metering unit

Field by field

The same fields come back for pdf, docx and html; only fileName changes.

Field	What it means
`documentId`	The identifier of the produced file. Downloads, status and sharing all go through it, so this is the one value worth storing.
`downloadUrl`	Relative to the API address and fetched with the same key. It is a path, not a public link.
`templateVersion`	Which version of the template produced this file. Keep it and a reprint months later can be explained.
`templateVersionSource`	published for a production render, draft when purpose was editor-test.
`pageCount`	How many pages were produced; this is what the quota counts.
`quotaRemaining`	Pages left in the current month, as of this response.
`meteringBasis`	What a page means for billing. pdf-equivalent counts a docx or html output as the same number of pages the PDF would have.
`previewUrl`	Filled only when the document was shared; null otherwise.

What usually goes wrong

downloadUrl is a path. Pasting it into a browser without the API address and the key gives a 404 or a 401, not the file.
Store documentId, not the whole response. Retention removes files after the period your plan keeps them, and a stored URL then points at nothing.
quotaRemaining is a snapshot of that moment, not a live counter. Two calls at once can both read the same number.
pageCount is the billing unit, not the number of files. A ten-page document costs ten pages whether you ask for pdf or docx.
previewUrl being null does not mean sharing failed; it means this render was not shared. Sharing is a separate call.