Skip to main content

Rendering

Endpoints for rendering templates to generate output documents in various formats.

Rendering Overview​

Templates can be rendered to multiple output formats:

  • pdf - PDF documents
  • html - HTML output
  • docx - Microsoft Word documents
  • xlsx - Microsoft Excel spreadsheets
  • text - Plain text

Rendering process:

  1. Resolve input parameters (from request or defaults)
  2. Execute processors to fetch data
  3. Build template context with data
  4. Execute template engine (Nunjucks, Handlebars, etc.)
  5. Apply output handler to generate final format

GET /api/templates/{id}/_render​

Render a template using GET parameters.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id), template.retrievePayload, template.resolveParams, template.processInputs, template.context, template.handler

Query Parameters:

ParameterTypeDescription
outputstringOutput format (pdf, html, docx, xlsx, text) - overrides template default
progressstringProgress tracking ID for long-running renders
downloadbooleanForce download with Content-Disposition header
filenamestringCustom filename for download
payloadIdstringID of stored payload from previous render
paramsobjectInput parameter values as JSON object

Additional parameters specific to inputs can be passed as query parameters.

Example Request:

GET /api/templates/abc123/_render?output=pdf&download=true&filename=report.pdf&params[report_title]=Q1%20Sales&params[start_date]=2024-01-01

Response:

Returns the rendered document with appropriate Content-Type header:

  • application/pdf for PDF
  • text/html for HTML
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document for DOCX
  • etc.

If download=true, includes Content-Disposition: attachment; filename="..." header.

POST /api/templates/{id}/_render​

Render a template using POST body for parameters.

Authentication: Required (session)

Pre-blocks: template.lookup(params.id), template.resolveParams, template.processInputs, template.context, template.handler

Query Parameters:

ParameterTypeDescription
outputstringOutput format (can also be in payload)
progressstringProgress tracking ID
downloadbooleanForce download (can also be in payload)
filenamestringCustom filename (can also be in payload)
paramsobjectInput parameters (can also be in payload)

Request Body:

FieldTypeDescription
outputstringOutput format override
progressstringProgress tracking ID
downloadbooleanForce download
filenamestringCustom filename
paramsobjectInput parameter values

Additional fields can be included for specific input values.

Example Request:

{
  "output": "pdf",
  "download": true,
  "filename": "quarterly-report.pdf",
  "params": {
    "report_title": "Q1 Sales Report",
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "region": "north"
  }
}

Response:

Returns the rendered document with appropriate content type and headers.

Timeout:

Socket timeout is set to 60 minutes (3,600,000ms) to accommodate long-running renders.

POST /api/templates/{id}/_render-params​

Store render parameters for later use (returns a payloadId for subsequent render calls).

Authentication: Required (session)

Pre-blocks: template.lookup(params.id)

Request Body:

Object containing parameter values and render options.

Example Request:

{
  "report_title": "Q1 Sales Report",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "region": "north",
  "output": "pdf"
}

Response:

{
  "payloadId": "payload-abc123",
  "expiresAt": "2024-01-16T10:30:00Z"
}

Use the returned payloadId in subsequent GET /api/templates/{id}/_render?payloadId=... requests.

Rendering Error Handling​

If processors encounter errors during rendering (e.g., dataset query fails, data source unavailable), the response depends on whether the template is a draft:

Draft templates: Returns an error page showing all processor errors with details.

Published templates: Returns an HTTP error response.

Example error response for drafts:

<html>
  <body>
    <h1>Template Rendering Errors</h1>
    <ul>
      <li>Processor 'sales_data': Dataset not found</li>
      <li>Processor 'summary': AI assistant unavailable</li>
    </ul>
  </body>
</html>

Progress Tracking​

For long-running renders, include a progress parameter to track rendering status via server-sent events or polling.

Handler Options​

Each output handler supports specific options in handlerOptions:

PDF Handler:

  • pageSize - Page size (letter, legal, a4, etc.)
  • margin - Margin size (CSS units)
  • orientation - portrait or landscape
  • header - Header configuration
  • footer - Footer configuration

DOCX Handler:

  • pageSize - Page size
  • margin - Margin configuration
  • orientation - portrait or landscape

XLSX Handler:

  • sheetName - Worksheet name
  • autoWidth - Auto-size columns