Core Operations
Endpoints for creating, reading, updating, deleting, and copying templates.
GET /api/templates
Get a paginated list of templates with HAL hypermedia links.
Authentication: Required (session)
Response:
Returns a paginated list of template objects.
POST /api/templates
Create a new template with optional initial files.
Authentication: Required (session)
Pre-blocks: permission.templates.create
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template name |
description | string | No | Template description |
type | string | No | Template engine: nunjucks, handlebars, pug (default: nunjucks) |
handler | string | No | Output handler: pdf, html, docx, xlsx, text (default: pdf) |
handlerOptions | object | No | Handler-specific configuration |
initialFiles | array | No | Array of initial files to create (default: []) |
initialFiles Array Items:
| Field | Type | Required | Description |
|---|---|---|---|
primary | boolean | No | Mark as primary template file (default: false) |
role | string | Yes | File role: TEMPLATE, ASSET, DATA |
filename | string | Yes | Filename with extension |
contentType | string | No | MIME type |
payload | string | No | File contents as string |
Example Request:
{
"name": "Monthly Report",
"description": "Generate monthly sales reports",
"type": "nunjucks",
"handler": "pdf",
"handlerOptions": {
"pageSize": "letter",
"margin": "1in"
},
"initialFiles": [
{
"primary": true,
"role": "TEMPLATE",
"filename": "report.html",
"contentType": "text/html",
"payload": "<html><body><h1>{{ title }}</h1></body></html>"
},
{
"role": "ASSET",
"filename": "styles.css",
"contentType": "text/css",
"payload": "body { font-family: Arial; }"
}
]
}
Response:
Returns the created template object with 201 Created status and Location header.
{
"id": "abc123",
"tenant": "acme",
"name": "Monthly Report",
"description": "Generate monthly sales reports",
"type": "nunjucks",
"handler": "pdf",
"handlerOptions": {
"pageSize": "letter",
"margin": "1in"
},
"ownerId": "john",
"slug": "monthly-report",
"shared": false,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
GET /api/templates-list
Get a simple list of all templates ordered by update time (legacy compatibility endpoint).
Authentication: Required (session)
Response:
Array of template objects without pagination.
GET /api/templates/{id}
Retrieve a specific template with full details.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id)
Response:
{
"id": "abc123",
"tenant": "acme",
"name": "Monthly Report",
"description": "Generate monthly sales reports",
"type": "nunjucks",
"handler": "pdf",
"handlerOptions": {
"pageSize": "letter",
"margin": "1in"
},
"ownerId": "john",
"slug": "monthly-report",
"shared": false,
"templateFileId": "file-123",
"editingId": null,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"_links": {
"self": { "href": "/api/templates/abc123" },
"inf:template-files": { "href": "/api/templates/abc123/files" },
"inf:template-processors": { "href": "/api/templates/abc123/processors" },
"inf:template-inputs": { "href": "/api/templates/abc123/inputs" },
"inf:render": { "href": "/api/templates/abc123/_render" }
}
}
PUT /api/templates/{id}
Update template properties.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id), permission.template.write(pre.template)
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Template name |
description | string | Template description (empty string allowed) |
type | string | Template engine type |
handler | string | Output handler |
handlerOptions | object | Handler-specific configuration |
shared | boolean | Share template publicly within tenant |
settings | object | Template settings |
letterheadId | string | null | Letterhead template ID |
Example Request:
{
"name": "Updated Monthly Report",
"description": "Enhanced monthly sales reports with charts",
"handlerOptions": {
"pageSize": "legal",
"margin": "0.5in"
}
}
Response:
Returns the updated template object.
DELETE /api/templates/{id}
Delete a template and all associated files, processors, and inputs.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id), permission.template.delete(pre.template)
Response:
Returns 204 No Content on successful deletion.
POST /api/templates/{id}/_copy
Create a copy of a template with all files, processors, and inputs.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id), permission.template.copy(pre.template), permission.templates.create
Request Body:
| Field | Type | Description |
|---|---|---|
name | string | Name for the copied template (optional, defaults to original name) |
progress | string | Progress tracking ID (optional) |
Example Request:
{
"name": "Copy of Monthly Report"
}
Response:
Returns the copied template object with 201 Created status and Location header.
POST /api/templates/{id}/_export
Export template as a portable package for import into another tenant.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id)
Response:
Returns a JSON export package containing template metadata, files, processors, and inputs.
POST /api/templates/{id}/_takeover
Take over editing of a template that is currently being edited by another user (admin only).
Authentication: Required (session)
Pre-blocks: template.lookup(params.id), permission.template.write(pre.template)
Response:
Returns success confirmation after taking over the template edit session.
GET /api/templates/{id}/owner
Get the owner (user or team) of a template.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id)
Response:
{
"id": "john",
"type": "user",
"_embedded": {
"inf:user": {
"id": "john",
"username": "john",
"email": "john@example.com",
"displayName": "John Doe"
}
}
}
PUT /api/templates/{id}/owner
Change the owner of a template.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id), permission.template.write(pre.template), permission.template.changeOwnerToTeam
Request Body:
| Field | Type | Description |
|---|---|---|
id | string | New owner principal ID (user or team) |
Example Request:
{
"id": "engineering-team"
}
Response:
Returns the updated template with new owner and creates an activity log entry.
GET /api/templates/{id}/datasets
Get all datasets associated with this template's processors.
Authentication: Required (session)
Pre-blocks: template.lookup(params.id)
Response:
Returns an array of dataset objects referenced by template processors.