Template Management

Import templates

Takes a list of template documents — what GET /api/v1/templates/{id} returns, one per template — and creates each as a new template at version 1: history and slug are not carried over (the slug is made from the name, with a numeric suffix when it is taken). The list rows of GET /api/v1/templates carry no html, so they are not an export.

Each entry is checked like a create; one that fails is reported in errors and the rest still land, so a 201 can carry refusals — read errors. The whole import is refused (422 resource_limit_exceeded) if it would take the account past 200 templates.

post/api/v1/templates/import

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/templates/import
  • 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

What landed, and one line per entry that did not

Changes

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