Skip to main content

Quick Start

This walkthrough takes you from a clean install to a rendered PDF in a few minutes.

1. Open the Studio​

Visit http://localhost:8080. There's no login — the Studio opens directly on your projects.

2. Create a report​

A report is Velkin's unit of rendering. Each report bundles:

  • a slug derived from its name (e.g. quick-start-invoice), used in API URLs,
  • one or more template assets (.html, .docx, .xlsx),
  • helpers.hbs, data.json (sample data), and options.json (output options).

From the Studio sidebar, click New project, name it Quick Start Invoice, and create it. The slug quick-start-invoice is generated from the name.

3. Add a template​

Add a new HTML template and name it template.html (the dialog pre-fills report.html — just replace it). Paste this Handlebars snippet:

<!doctype html>
<html>
  <head><meta charset="utf-8"><title>Invoice {{number}}</title></head>
  <body style="font-family: Inter, sans-serif; padding: 40px;">
    <h1>Invoice #{{number}}</h1>
    <p>Bill to: <strong>{{customer.name}}</strong></p>
    <table style="width:100%; border-collapse: collapse; margin-top: 24px;">
      <thead><tr><th align="left">Item</th><th align="right">Amount</th></tr></thead>
      <tbody>
      {{#each items}}
        <tr><td>{{description}}</td><td align="right">{{amount}} €</td></tr>
      {{/each}}
      </tbody>
    </table>
  </body>
</html>

Click Save in the topbar to persist the template to the report.

Adding a template does not make it the one that gets rendered — you have to pick it. Open the options.json tab and choose template.html as the active template from the selector above the editor (this sets outputOptions.template), then Save again. Until a report has an active template, the render endpoints return 422 select a template via outputOptions.template before rendering.

4. Render via the API​

The render endpoint takes the report slug in the path and a JSON body with a data object. No authorization header is required:

curl -X POST http://localhost:8081/api/reports/quick-start-invoice/render-pdf \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "number": "2024-001",
      "customer": { "name": "Acme Corp." },
      "items": [
        { "description": "Widget A", "amount": "120.00" },
        { "description": "Widget B", "amount": "240.00" }
      ]
    }
  }' \
  --output invoice.pdf

Open invoice.pdf — you should see your rendered document.

Sample data

If you omit data from the request body, Velkin falls back to the report's saved sample data (data.json). That makes render-pdf with an empty body a quick way to smoke-test a template.

What's next​