Template Management

Update a template (new version)

Send only what changes: the body is merged over the current version, and a field it leaves out keeps its value ({"width": 1080, "height": 1080} is a whole update); "" empties css or description. variables, when not sent, stay as they are unless html or css changes, and are then derived from the new markup. Same limits as create. Never edits in place: the template moves to version + 1 — every PUT does, a rename included — and the previous bytes stay readable as {id}@{version}, so a job or automation that pinned a version keeps rendering exactly that. Built-in ids are 403; to start from one, create your own with its html.

put/api/v1/templates/{id}

Request

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

Path parameters

idstring required

Template id or your own slug

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 its new version

Changes

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