Output Formats

Velkin renders the report's active template (the asset named by outputOptions.template). What you get back depends on the endpoint you call and the kind of the active template.

The matrix

Active template	render-pdf	render-docx	render-xlsx
HTML	✅ PDF via Chromium	❌ kind mismatch	❌ kind mismatch
DOCX	✅ PDF via soffice	✅ native .docx	❌ kind mismatch
XLSX	✅ PDF via soffice	❌ kind mismatch	✅ native .xlsx

• render-pdf works for any active template. HTML is rendered by Chromium; DOCX/XLSX are filled and then converted to PDF by LibreOffice (soffice).
• render-docx / render-xlsx return the filled-in native Office file. They require the active template to be of the matching kind, otherwise the API responds 400 kind_mismatch.

The endpoints are deterministic: render-pdf always returns PDF, render-docx always returns DOCX, render-xlsx always returns XLSX. There is no HTML download endpoint — HTML is produced only for the Studio preview endpoints (/preview and /preview-html), which always return text/html (see below).

What preferredOutput actually does

{
  "template": "invoice.docx",
  "preferredOutput": "pdf"
}

preferredOutput (pdf | native) is a Studio hint, not a render switch. The render endpoints never act on it — the backend only validates the value. It tells the Studio which endpoint its download button should call for a binary template:

• "pdf" → the download button calls render-pdf (converted PDF).
• "native" → the download button calls render-docx / render-xlsx (the editable Office file).

If you call the API directly, you pick the format by choosing the endpoint — preferredOutput has no effect.

Choosing a format

If you need…	Active template	Endpoint
Pixel-perfect, print-ready layout	HTML	render-pdf
Editable invoice the recipient can modify	DOCX	render-docx
Financial report with formulas they'll keep editing	XLSX	render-xlsx
Frozen PDF snapshot of a Word/Excel template	DOCX / XLSX	render-pdf

API mapping

Endpoint	Output
POST /api/reports/:slug/render-pdf	PDF for any active template kind.
POST /api/reports/:slug/render-docx	Native DOCX (requires a DOCX active template).
POST /api/reports/:slug/render-xlsx	Native XLSX (requires an XLSX active template).
POST /api/reports/:slug/preview	text/html preview for any kind (see note below).
POST /api/reports/:slug/preview-html	text/html — requires an HTML active template.

The preview endpoints always return HTML

The two preview endpoints power the Studio's preview, and both respond with text/html — never a PDF or a binary file:

• preview-html renders an HTML active template and returns the compiled HTML. It rejects non-HTML templates with 422 html_preview_unavailable.
• preview works for any kind. For HTML it returns the compiled HTML; for DOCX/XLSX it returns an approximate HTML rendering produced by LibreOffice (soffice --convert-to xhtml). This is a cheap, embeddable preview — it is not the print-accurate PDF, so expect some layout drift versus render-pdf.

To get the print-accurate output, call the render-* endpoints.

See the full API reference for request and response shapes.