Template

A Template represents a reusable content block using a template syntax. Each template declares its format (HTML, Markdown, or plain text), lists the variable fields it expects, and maintains a version history through automatic new-version creation on every update.

Sample Object

{
  "id": "tpl_abc123def456",
  "created": "2026-07-21T10:30:00Z",
  "key": "welcome_email_html",
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1><p>Your {{.Product}} account is ready.</p>",
  "fields": ["Name", "Product"],
  "parent_id": "tpl_abc123def456",
  "author_id": "usr_xyz789ghi012",
  "versions": 3
}

Fields

Field	Type	Description
`id`	`string`	Unique identifier for the template, generated by the platform.
`created`	`timestamp`	RFC 3339 timestamp indicating when the template was first created.
`key`	`string`	A normalized, unique key derived from the display name and format. Used as the primary identifier in API operations.
`display_name`	`string`	The human-readable name of the template. This value is normalized to produce the key.
`format`	`string`	The content format of the template. Allowed values: `html`, `md`, `text`. Defaults are validated at creation time.
`content`	`string`	The template body written in template syntax. This is the content that gets parsed and executed with provided data.
`fields`	`array of strings`	List of variable names that the template expects. Documenting fields helps consumers understand what data to provide at render time.
`parent_id`	`string`	The ID of the first version in the template’s version chain. All versions of the same template share this value.
`author_id`	`string`	The user ID of the template’s author. Set automatically from the authenticated user on creation and update.
`versions`	`int`	The number of versions that exist for this template. Increments automatically on each update.

Actions

Creating a template

Create a new template by providing its display name, format, content body, and expected fields. The platform normalizes the display name into a unique key by lowercasing, stripping special characters, and appending the format suffix. The template’s parent_id is set to its own ID, establishing the first entry in the version chain.

obx app templates init "Welcome Email" --format html

Edit the generated files, then push to the platform:

obx app templates push welcome_email_html

POST /api/v1/templates

{
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1>",
  "fields": ["Name"]
}

Successful response

{
  "id": "tpl_abc123def456",
  "created": "2026-07-21T10:30:00Z",
  "key": "welcome_email_html",
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1>",
  "fields": ["Name"],
  "parent_id": "tpl_abc123def456",
  "author_id": "usr_xyz789ghi012",
  "versions": 1
}

Getting a template by key

Retrieve a single template using its unique key. This returns the latest version of the template. The key is the normalized identifier derived from the display name and format (e.g., welcome_email_html).

obx app templates pull welcome_email_html

GET /api/v1/templates/welcome_email_html

Successful response

{
  "id": "tpl_abc123def456",
  "created": "2026-07-21T10:30:00Z",
  "key": "welcome_email_html",
  "display_name": "Welcome Email",
  "format": "html",
  "content": "<h1>Welcome, {{.Name}}!</h1>",
  "fields": ["Name"],
  "parent_id": "tpl_abc123def456",
  "author_id": "usr_xyz789ghi012",
  "versions": 1
}

Listing all templates

Retrieve all templates in the project. Each entry represents the latest version of a template, with the versions field indicating how many total versions exist for that template.

obx app templates list

GET /api/v1/templates

Successful response

{
  "items": [
    {
      "id": "tpl_abc123def456",
      "key": "welcome_email_html",
      "display_name": "Welcome Email",
      "format": "html",
      "versions": 3
    },
    {
      "id": "tpl_ghi789jkl012",
      "key": "password_reset_html",
      "display_name": "Password Reset",
      "format": "html",
      "versions": 1
    }
  ]
}

Updating a template

Update a template by providing new content or fields. The platform preserves the original key, display name, format, and parent ID from the existing template. A new version is created automatically – the content and fields are updated but the parent_id remains pointing to the first version, establishing a version chain.

obx app templates push welcome_email_html

const result = await oblax.templates.template.update("welcome_email_html", {
  content:
    "<h1>Welcome, {{.Name}}!</h1><p>Your {{.Product}} account is ready.</p>",
  fields: ["Name", "Product"],
});

PUT /api/v1/templates/welcome_email_html

{
  "content": "<h1>Welcome, {{.Name}}!</h1><p>Your {{.Product}} account is ready.</p>",
  "fields": ["Name", "Product"]
}

Successful response

{
  "change": true
}

Deleting a template

Delete a template by its key. This operation removes the template and all its versions.

obx app templates delete welcome_email_html

Rendering a template with data

Execute a template by providing values for its declared fields. The platform fetches the latest version of the template by key, parses it with the template engine, and returns the rendered output. This is the primary way to generate content from templates at runtime.

Rendering is available through the SDK and REST API.

POST /api/v1/templates/welcome_email_html/render

{
  "Name": "Jane Doe",
  "Product": "Oblax Cloud"
}

Successful response

{
  "content": "<h1>Welcome, Jane Doe!</h1><p>Your Oblax Cloud account is ready.</p>"
}