> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Promote Surface to Imprint

> POST /v0/surfaces/{publicId}/promote-to-imprint — Ship a mount surface as an imprint starter template

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.

<Note>
  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.
</Note>

## Path parameters

| Parameter  | Type   | Required | Description                                                              |
| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
| `publicId` | string | Yes      | Surface public UUID (must be a surface on a mount of an imprint you own) |

## Body

| Field     | Type    | Required | Description                                                                                                                                                                |
| --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alias`   | string  | No       | Manifest 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). |
| `default` | boolean | No       | Make this the imprint's default surface. At most one template may be `default`.                                                                                            |

## Response

```json theme={null}
{
  "ok": true,
  "data": {
    "alias": "signals-board",
    "htmlArtifactAlias": "my-imprint-surface-signals-board",
    "default": true
  }
}
```

## Errors

| Status | Code                                | Cause                                                                                        |
| ------ | ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `404`  | `SURFACE_NOT_FOUND`                 | No Surface with that public id is owned by the caller                                        |
| `400`  | `SURFACE_NOT_ON_MOUNT`              | The surface is standalone — only a mount surface can be templated                            |
| `403`  | `SURFACE_PROMOTE_NOT_IMPRINT_OWNER` | The caller does not own the surface's imprint                                                |
| `400`  | `SURFACE_BINDING_NOT_TEMPLATABLE`   | A binding points at an ad-hoc table/artifact not declared in the manifest — declare it first |
| `400`  | `SURFACE_DEFAULT_CONFLICT`          | A second template was marked `default: true`                                                 |