Template API Overview

The Informer Template API provides comprehensive endpoints for creating and managing document templates. Templates are used to generate formatted output (PDF, HTML, Word, etc.) from data using template engines like Nunjucks or Handlebars. All routes are prefixed with /api.

Features

• CRUD Operations - Create, read, update, and delete templates
• File Management - Upload and manage template files (templates, assets, data files)
• Processors - Add data sources (datasets, queries, AI assistants) to templates
• Inputs - Define user input parameters for template rendering
• Rendering - Generate output in multiple formats (PDF, HTML, DOCX, etc.)
• Drafts & Versioning - Create draft copies for safe editing without affecting production
• Sharing & Permissions - Team-based access control and ownership management
• Comments - Add and view comments on templates
• Export/Import - Export templates for reuse or backup
• Favorites - Mark templates as favorites for quick access

Template Types

Templates support multiple template engines:

Type	Description
nunjucks	Nunjucks templating engine (default)
handlebars	Handlebars templating engine
pug	Pug (formerly Jade) templating engine

Template Handlers

Handlers control the output format:

Handler	Description
pdf	Generate PDF documents (default)
html	Generate HTML output
docx	Generate Microsoft Word documents
xlsx	Generate Microsoft Excel spreadsheets
text	Generate plain text output

Authentication

All Template API endpoints require authentication via session cookies or API tokens. Most endpoints verify template permissions before allowing access.

Common Permission Patterns

• Read access - View template structure and files
• Write permission - Required for template:write (create, update, delete, file changes, processor/input modifications)
• Copy permission - Required for template:copy (copy templates)
• Delete permission - Required for template:delete (remove templates)

Template Structure

A template consists of:

• Template File - Primary template file (HTML, Nunjucks, etc.)
• Asset Files - CSS, JavaScript, images, fonts
• Data Files - Static JSON/CSV data
• Processors - Dynamic data sources (datasets, queries, assistants)
• Inputs - User-provided parameters for rendering
• Settings - Handler-specific configuration (page size, margins, etc.)

Template Workflow

Creating a Template

1. Create template - POST /api/templates with initial files
2. Add processors - POST /api/templates/\{id\}/processors to add data sources
3. Add inputs - POST /api/templates/\{id\}/inputs to define parameters
4. Configure settings - PUT /api/templates/\{id\}/settings for output options
5. Render - POST /api/templates/\{id\}/_render to generate output

Editing with Drafts

Templates support draft mode for safe editing:

1. Create draft - POST /api/templates/\{id\}/_edit
2. Modify draft - Make changes to files, processors, inputs
3. Commit draft - POST /api/templates/\{id\}/draft/_commit to publish changes
4. Delete draft - DELETE /api/templates/\{id\}/draft to discard changes

Processors

Processors provide data to templates during rendering. Each processor runs in a specific phase:

Phase	Description
data	Fetch data before rendering (datasets, queries)
pre	Pre-process data before template execution
post	Post-process output after template execution

Common processor types:

• dataset - Query a dataset and make results available
• datasource - Execute a datasource query directly
• assistant - Generate AI-powered content
• query - Execute a saved query

Inputs

Inputs define user parameters for template rendering. Input types include:

• text - Single-line text
• textarea - Multi-line text
• number - Numeric value
• date - Date picker
• select - Dropdown list
• checkbox - Boolean value
• radio - Radio button group

Inputs can have validation rules, default values, and be marked as required.

Common Query Parameters

Many template endpoints support:

Parameter	Type	Default	Description
output	string	handler default	Output format (pdf, html, docx, etc.)
download	boolean	false	Force download with filename
filename	string	-	Custom filename for downloads
params	object		Input parameter values
progress	string	-	Progress tracking ID

Error Responses

Standard HTTP status codes:

• 200 - Success
• 201 - Created (new resource)
• 400 - Bad request (validation error)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 500 - Internal server error

Error responses include:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error: 'type' must be a valid template driver"
}

Next Steps

Explore the specific endpoint categories:

• Core Operations - CRUD, copy, export
• Files - File upload and management
• Processors - Data source management
• Inputs - Parameter management
• Rendering - Generate output
• Drafts - Draft workflow
• Sharing - Ownership and permissions
• Comments & Favorites - User interactions