API

Render API

Render reports to HTML or PDF via the REST API with template-based or inline schema requests.

Endpoint

POST /api/render

The render endpoint accepts a report schema and data, then returns the rendered output in HTML or PDF format.

Request modes

Mode 1: Template-based rendering

Use a pre-registered template by its ID:

{
  "templateId": "invoice-v1",
  "data": {
    "company": { "name": "Acme Corp" },
    "items": [{ "description": "Widget", "quantity": 2, "price": 29.99 }]
  },
  "format": "html"
}

Mode 2: Inline template

Send the full schema inline for ad-hoc reports:

{
  "template": {
    "version": "1.0",
    "type": "report",
    "page": { "size": "A4", "orientation": "portrait" },
    "bands": [
      {
        "type": "header",
        "height": 40,
        "components": [
          {
            "type": "text",
            "position": { "x": 0, "y": 10, "width": 200, "height": 20 },
            "content": "{{title}}",
            "fontSize": 18,
            "fontWeight": "bold"
          }
        ]
      }
    ]
  },
  "data": {
    "title": "My Report"
  },
  "format": "html"
}

Format options

FormatContent-TypeDescription
htmlapplication/jsonJSON response with HTML output
pdfapplication/pdfBinary PDF stream

HTML response

When format is html, the response is a JSON object:

{
  "output": "<div class=\"report\">...</div>",
  "metadata": {
    "pageCount": 1,
    "renderTimeMs": 42,
    "format": "html"
  }
}

PDF response

When format is pdf, the response is a binary PDF stream with Content-Type: application/pdf. The response includes metadata headers:

Content-Type: application/pdf
X-Page-Count: 2
X-Render-Time-Ms: 350

PDF rendering requires Puppeteer (headless Chromium). See the Docker guide for production setup.

Examples

HTML with curl

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "invoice-v1",
    "data": {
      "company": { "name": "Acme Corp" },
      "invoiceNumber": "INV-001",
      "items": [
        { "description": "Service", "quantity": 1, "unitPrice": 500, "total": 500 }
      ]
    },
    "format": "html"
  }'

PDF with curl

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -o invoice.pdf \
  -d '{
    "templateId": "invoice-v1",
    "data": {
      "company": { "name": "Acme Corp" },
      "invoiceNumber": "INV-001",
      "items": [
        { "description": "Service", "quantity": 1, "unitPrice": 500, "total": 500 }
      ]
    },
    "format": "pdf"
  }'

Error responses

StatusDescription
400Invalid request body or schema validation error
404Template not found (template-based mode)
500Internal rendering error

Error response body:

{
  "error": "VALIDATION_ERROR",
  "message": "Schema validation failed",
  "details": [{ "path": "bands[0].height", "message": "height is required" }]
}

Next steps