Appearance
Update template
PUT
/api/v1/templates/{id}
Updates the template. Writes the published copy by default, so the change is live on the next render; pass stage: "draft" to stage it for a later publish instead. Switching from blocks to code is irreversible. Pass folder to move the template: a path like marketing/onboarding (missing folders are created), or null to unfile it to the root: folder moves require an API key. Bearer tokens must match the template and must not be readonly.
Authorizations
ApiKeyAuth
Long-lived account credential. Create one from the dashboard.
Type
API Key (header: x-api-key)
or
BearerAuth
Short-lived presigned token scoped to a single template (minted via /presigned-url).
Type
HTTP (bearer)
Parameters
Path Parameters
id*
Type
Requiredstring
Example
"bonipyZlnbwtYVSzQO3AA"Request Body
application/json
Min Length
1Max Length
128Structural JSON value: object or array. Scalars and null are rejected.
Block tree (visual mode). Authored via the editor; rarely hand-written. See the Postcraft dashboard's editor for the full discriminated union of block kinds.
Email subject line, as Handlebars rendered against the render context. null removes it; omit it to keep the stored one.
Max Length
998Folder path to move the template to, e.g. "marketing/onboarding". Segments are created if missing; null unfiles it to the root; omit to leave the folder unchanged. Requires an API key.
Max Length
512Which copy to write. published (the default) changes what renders immediately; draft stages the change until the template is published.
Valid values
"draft""published"The updatedAt from your last read or write of this template. The write is refused with 409 if anyone has written since, so re-read and reapply your change. Omit it to overwrite whatever is there.
Responses
Template updated.
application/json
When the published copy last changed. Unmoved by a draft write.
False when the write stored nothing new, because the body restated what was already there.
Problems found in the template. Advisory rather than fatal: a template that renders can still carry warnings, while an error severity is one that will not.