Templates API
Manage reusable document templates. Templates store document definitions that can be combined with data at generation time to produce personalized PDFs.
All endpoints require authentication and are scoped to a tenant.
GET /templates
List all templates for the tenant.
Endpoint
GET /api/v1/tenants/{tenantId}/templates
Response
Success (200 OK)
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"parentId": null,
"tenantId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
"name": "Shipping Invoice",
"content": "{ \"documentDefinition\": { ... } }",
"testData": "{ \"client\": { ... } }",
"createdAt": "2026-03-15T10:00:00Z",
"createdBy": "laura.bennett@shipforge.io",
"owner": "laura.bennett@shipforge.io",
"updatedAt": "2026-03-28T14:30:00Z",
"revision": "rev-20260328T143000"
}
]
GET /templates/names
List template names only (lightweight summary).
Endpoint
GET /api/v1/tenants/{tenantId}/templates/names
Response
Success (200 OK)
Returns the latest version of each uniquely named template.
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Shipping Invoice"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Delivery Receipt"
}
]
POST /templates
Create a new template.
Endpoint
POST /api/v1/tenants/{tenantId}/templates
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template name (max 100 characters) |
content | string | Yes | JSON document definition as a string |
testData | string | No | Sample data JSON for preview/testing |
createdBy | string | Yes | Author identifier (max 100 characters) |
owner | string | No | Owner identifier (max 100 characters) |
parentId | string (GUID) | No | Parent template ID for revision chains |
{
"name": "Shipping Invoice",
"content": "{\"documentDefinition\":{\"contents\":[{\"p\":\"Invoice for $data.client.name\"}]}}",
"testData": "{\"client\":{\"name\":\"Test Corp\"}}",
"createdBy": "laura.bennett@shipforge.io",
"owner": "laura.bennett@shipforge.io"
}
Response
Success (201 Created)
Returns the created template with a generated id, revision, and timestamps.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"parentId": null,
"tenantId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
"name": "Shipping Invoice",
"content": "{\"documentDefinition\":{\"contents\":[{\"p\":\"Invoice for $data.client.name\"}]}}",
"testData": "{\"client\":{\"name\":\"Test Corp\"}}",
"createdAt": "2026-03-30T14:30:00Z",
"createdBy": "laura.bennett@shipforge.io",
"owner": "laura.bennett@shipforge.io",
"updatedAt": "2026-03-30T14:30:00Z",
"revision": "rev-20260330T143000"
}
GET /templates/{id}
Get a single template by ID.
Endpoint
GET /api/v1/tenants/{tenantId}/templates/{id}
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | string (GUID) | Template identifier |
Response
Success (200 OK)
Returns the full template object.
Error (404 Not Found)
Returned when no template with the given ID exists for this tenant.
PUT /templates/{id}
Update an existing template. This creates a new revision linked to the previous version.
Endpoint
PUT /api/v1/tenants/{tenantId}/templates/{id}
Request body
| Field | Type | Required | Description |
|---|---|---|---|
id | string (GUID) | Yes | Must match the {id} path parameter |
name | string | No | Updated template name |
content | string | Yes | Updated document definition |
testData | string | No | Updated test data |
createdBy | string | No | Author identifier |
owner | string | No | Owner identifier |
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Shipping Invoice v2",
"content": "{\"documentDefinition\":{\"contents\":[{\"p\":\"Updated invoice for $data.client.name\"}]}}",
"testData": "{\"client\":{\"name\":\"Test Corp\"}}",
"createdBy": "laura.bennett@shipforge.io",
"owner": "laura.bennett@shipforge.io"
}
Response
Success (204 No Content)
The template was updated successfully.
Error (400 Bad Request)
Returned when the id in the body does not match the path parameter.
Error (404 Not Found)
Returned when no template with the given ID exists.
DELETE /templates/{id}
Delete a template.
Endpoint
DELETE /api/v1/tenants/{tenantId}/templates/{id}
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | string (GUID) | Template identifier |
Response
Success (204 No Content)
The template was deleted.
Error (404 Not Found)
Returned when no template with the given ID exists.
Template revisions
Templates support versioning through revisions. Each update creates a new revision linked to its parent.
POST /templates/{templateId}/revisions
Create a new revision of a template.
POST /api/v1/tenants/{tenantId}/templates/\{templateId\}/revisions
GET /templates/{templateId}/revisions
List all revisions of a template, ordered by most recent first.
GET /api/v1/tenants/{tenantId}/templates/\{templateId\}/revisions
DELETE /templates/{templateId}/revisions/{revisionId}
Delete a specific revision.
DELETE /api/v1/tenants/{tenantId}/templates/\{templateId\}/revisions/\{revisionId\}
POST /templates/{templateId}/revisions/{revisionId}/revert
Revert a template to a previous revision. This creates a new revision with the content from the specified historical revision.
POST /api/v1/tenants/{tenantId}/templates/\{templateId\}/revisions/\{revisionId\}/revert