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/{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/{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/{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/{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/{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/{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/{tenantId}/templates/\{templateId\}/revisions

GET /templates/{templateId}/revisions

List all revisions of a template, ordered by most recent first.

GET /api/v1/{tenantId}/templates/\{templateId\}/revisions

DELETE /templates/{templateId}/revisions/{revisionId}

Delete a specific revision.

DELETE /api/v1/{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/{tenantId}/templates/\{templateId\}/revisions/\{revisionId\}/revert