Templates API

Endpoint

GET /api/templates/:id

The templates endpoint returns a registered report template along with its sample data. This is useful for testing, populating the designer, and template-based rendering.

Request

Retrieve a template by its ID:

GET /api/templates/invoice-v1

No request body is required.

Response

The response includes the full template schema and sample data:

{
  "id": "invoice-v1",
  "name": "Invoice",
  "description": "Standard invoice template with company header, line items, and totals",
  "template": {
    "version": "1.0",
    "type": "report",
    "page": { "size": "A4", "orientation": "portrait" },
    "bands": [...]
  },
  "sampleData": {
    "company": { "name": "Acme Corp", "address": "123 Main St" },
    "invoiceNumber": "INV-001",
    "items": [
      { "description": "Service", "quantity": 1, "unitPrice": 500, "total": 500 }
    ]
  }
}

Available templates

Template ID	Description
invoice-v1	Standard invoice with header, line items, totals
simple-list-v1	Simple list report with header and detail rows

List all templates

To list all available templates:

GET /api/templates

Response:

{
  "templates": [
    {
      "id": "invoice-v1",
      "name": "Invoice",
      "description": "Standard invoice template with company header, line items, and totals"
    },
    {
      "id": "simple-list-v1",
      "name": "Simple List",
      "description": "Simple list report with header and detail rows"
    }
  ]
}

Using templates with render

Once you have a template ID, use it with the Render API:

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "invoice-v1",
    "data": {
      "company": { "name": "My Company" },
      "invoiceNumber": "INV-042",
      "items": [
        { "description": "Consulting", "quantity": 8, "unitPrice": 150, "total": 1200 }
      ]
    },
    "format": "html"
  }'

Testing with sample data

Fetch a template and render it with its own sample data for quick testing:

// Fetch template with sample data
const res = await fetch('/api/templates/invoice-v1')
const { template, sampleData } = await res.json()

// Render with sample data
const renderRes = await fetch('/api/render', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template,
    data: sampleData,
    format: 'html',
  }),
})

const { output } = await renderRes.json()

Error responses

Status	Description
404	Template not found
500	Internal server error

{
  "error": "NOT_FOUND",
  "message": "Template 'unknown-template' not found"
}

Next steps

• Render API — render templates with custom data
• Validate API — validate template schemas
• Schema Overview — understand the template schema structure