Template Management

Create a template

Creates version 1 and answers 201 with it. name, html, width and height are required. html ≤ 256 KB and css ≤ 128 KB (UTF-8 bytes), width / height 1–4096 px; anything outside is 400 invalid_param naming the field. variables defaults to the {{ … }} names found in the html and css. Each account may own at most 200 templates (422 resource_limit_exceeded).

Rendering is POST /api/v1/jobs {"op": "render_template", "templateId": …, "items": [...]}, or one row now with POST /api/v1/images/render.

post/api/v1/templates

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/templates
  • Auth: API key in header Authorization

Headers

Idempotency-Keystring

Optional. A client-generated unique key (typically a UUID). Same key + the same request (method, path, query string and body) replays the first response verbatim with Idempotency-Replayed: true, without executing again. Same key + a different one returns 409 idempotency_key_reuse. A repeat that arrives while the first is still running returns 409 request_in_progress, which is retryable. Keys are retained 24 hours. At most 255 characters; a longer one is a 400 invalid_param with param: "Idempotency-Key".

Request body

idstring

Template id (tpl_…; a built-in's is builtin-template-…). A version read by id@version carries that spelling here.

namestring

Display name (required on create; at most 200 characters)

slugstring

URL-safe handle, unique per account: lowercase letters, digits and hyphens. Generated from the name when omitted; one you send must be free. builtin- is reserved.

descriptionstring

Free text for people; not rendered. "" on a PUT empties it.

htmlstring

Body HTML (required on create; ≤ 256 KB as UTF-8). Scripts never run; every request it makes is blocked at render time except data: URIs and this product's own asset host.

cssstring

Stylesheet (≤ 128 KB as UTF-8). Like the html, it loads nothing but data: URIs and this product's own asset host; any other @import or url() is blocked at render time.

widthinteger

Viewport / output width in px (required on create; 1–4096)

heightinteger

Viewport / output height in px (required on create; 1–4096)

variablesstring[]

Placeholder names (at most 100, each letters, digits, _ and .). Derived from the html/css when omitted. A render fills {{ name }} HTML-escaped and {{{ name }}} raw; a name the row does not carry renders as nothing.

versioninteger

Current version; every PUT increments it and keeps the old one readable as id@version

builtInboolean

Whether this is a built-in template (read-only; PUT and DELETE are 403)

createdAtstring date-time

When the template — or, read as id@version, that version — was created

updatedAtstring date-time

When the current version was saved; absent on a version read as id@version

Example request

{
  "name": "Quote card",
  "width": 1080,
  "height": 1350,
  "html": "<main><blockquote>{{ quote }}</blockquote><cite>{{ author }}</cite></main>",
  "css": "main{display:grid;place-items:center;height:100%;font-family:system-ui}",
  "variables": [
    "quote",
    "author"
  ]
}

Response

The template, at version 1

Changes

No recorded changes to this operation across all 1 revision of this API.