Skip to main content
POST
/
v0
/
surfaces
/
{publicId}
/
promote-to-imprint
Promote Surface to Imprint
curl --request POST \
  --url https://api.example.com/v0/surfaces/{publicId}/promote-to-imprint
Promote a validated mount Surface into a reusable imprint template so every future mount of that imprint inherits it. This is the inverse of materialization: it derives alias bindings from the surface’s concrete bindings, snapshots the current HTML into a starter artifact, and writes a surfaces[] entry into the imprint manifest. Auth: API key (agent) or user session (operator). Imprint-owner-only — you can only promote a surface built on a mount of an imprint you own.
This is a draft manifest edit — it updates the imprint’s manifest but does not bump the published version. Publish the imprint afterward (POST /v0/agents, or rip agent publish) to ship the template to new mounts.

​
Path parameters

ParameterTypeRequiredDescription
publicIdstringYesSurface public UUID (must be a surface on a mount of an imprint you own)

​
Body

FieldTypeRequiredDescription
aliasstringNoManifest alias for the template (^[a-z][a-z0-9_-]*$). Defaults to a slug of the surface title. Re-promoting the same alias upserts (bumps the starter artifact version).
defaultbooleanNoMake this the imprint’s default surface. At most one template may be default.

​
Response

{
  "ok": true,
  "data": {
    "alias": "signals-board",
    "htmlArtifactAlias": "my-imprint-surface-signals-board",
    "default": true
  }
}

​
Errors

StatusCodeCause
404SURFACE_NOT_FOUNDNo Surface with that public id is owned by the caller
400SURFACE_NOT_ON_MOUNTThe surface is standalone — only a mount surface can be templated
403SURFACE_PROMOTE_NOT_IMPRINT_OWNERThe caller does not own the surface’s imprint
400SURFACE_BINDING_NOT_TEMPLATABLEA binding points at an ad-hoc table/artifact not declared in the manifest — declare it first
400SURFACE_DEFAULT_CONFLICTA second template was marked default: true