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

# Create a builder template

> POST /v1/embed/builder/templates — create a template in a partner project from a builder draft. Accepts a partner API key or an embed session JWT.

<Info>**POST** `https://api.craftkit.dev/v1/embed/builder/templates`</Info>

Creates a template in the authenticated partner's project from a builder draft. The draft is
stored verbatim; if the caller has publish rights and the `layout` parses as a render-ready
document, a first version is published automatically.

## Authorization

Accepts **either** a partner API key **or** an embed session JWT.

<ParamField header="Authorization" type="string" required>
  `Bearer ck_live_…` (partner API key — grants `saveDraft` and `publish`) **or**
  `Bearer <session_token>` (embed session JWT — rights come from the session's `permissions`
  claims, and the request must originate from an allow-listed iframe origin).
</ParamField>

## Body

<ParamField body="documentTemplate" type="object" required>
  The builder draft to persist. Stored as-is; the whole object is returned (adapted) in the
  response. Only `name`, `layout`, and `presetKey` are interpreted server-side — all other keys
  round-trip through the draft.

  <Expandable title="documentTemplate">
    <ParamField body="name" type="string" default="Untitled template">
      Template display name. The slug is derived from it and suffixed with a short random token.
    </ParamField>

    <ParamField body="layout" type="object">
      The builder's internal canvas draft (`react-email-dnd` `CanvasDocument`). **Not** validated
      on create — publishing parses it and silently skips publish if it does not match the
      render-ready shape.
    </ParamField>

    <ParamField body="presetKey" type="string | null" default="null">
      Template-type identifier (for example `charter-handover`).
    </ParamField>
  </Expandable>
</ParamField>

## Response

`200` with the created template, adapted to the builder's `documentTemplate` shape.

<ResponseField name="documentTemplate" type="object">
  <Expandable title="documentTemplate">
    <ResponseField name="_id" type="string">New template UUID. Use it as `templateExternalId` when minting a fill session.</ResponseField>
    <ResponseField name="organizationId" type="string">The owning project's id.</ResponseField>

    <ResponseField name="name" type="string" />

    <ResponseField name="sD" type="boolean">Soft-delete flag; `false` for a new template.</ResponseField>
    <ResponseField name="cAt" type="string">ISO-8601 creation timestamp.</ResponseField>

    <ResponseField name="presetKey" type="string | null" />

    <ResponseField name="layout" type="object | null">The persisted builder layout draft.</ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | code                               | Meaning                                                                |
| ------ | ---------------------------------- | ---------------------------------------------------------------------- |
| 400    | `invalid_json`                     | Body is not valid JSON.                                                |
| 401    | `missing_or_invalid_authorization` | No bearer token, or neither a valid API key nor a valid session token. |
| 403    | `permission_denied`                | Authenticated, but the session lacks `saveDraft` rights.               |
| 500    | `insert_failed`                    | The template row could not be written.                                 |

```bash cURL theme={null}
curl -X POST https://api.craftkit.dev/v1/embed/builder/templates \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentTemplate": {
      "name": "Charter Handover",
      "presetKey": "charter-handover",
      "layout": { "sections": [] }
    }
  }'
```

```json 200 theme={null}
{
  "documentTemplate": {
    "_id": "0193c2c3-...",
    "organizationId": "proj_01j...",
    "name": "Charter Handover",
    "sD": false,
    "cAt": "2026-06-05T10:00:00.000Z",
    "presetKey": "charter-handover",
    "isCustomTemplate": true,
    "layout": { "sections": [] },
    "design": null
  }
}
```