---
title: "Publish a template document, or import a public catalog slug"
method: POST
path: "/v1/templates"
tags: ["templates"]
---

# Publish a template document, or import a public catalog slug

`POST /v1/templates`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/templates`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `projects:write`)
  - API key in header `PAYMENT-SIGNATURE`

Store a template document for this org (the kernel validates its schema and every `{{name}}` reference; a republish of the same slug bumps its version), or import a slug from the public catalog (cueframe-ai/cueframe-templates) as this org's copy. The document is capped at 1 MiB. With `dryRun: true` nothing is stored: the answer is 200 with the kernel's problems as data, for the document alone or, when `values`, `media` or `preset` are given, for those inputs bound against this org's media rows.

## Request body

- union
  - TemplatePublishDocumentRequest
    - `document` TemplateDocument, required: A CueFrame template document (kernel TemplateDocument): v: 1, slug, name, composition with {{name}} references, parameters, components by value, an optional brandKit, presets, rubric, gallery and provenance.
    - `dryRun` boolean: When true, store nothing: answer 200 with the kernel's verdict on the document as `TemplateValidateResponse`. Without `values`, `media` or `preset` the document itself is checked (every preset binds against the parameters' samples and placeholder values for required parameters that have no default). With any of them, only the caller's inputs are bound, `{ mediaId }` values against this org's real media rows.
    - `values` object: Dry run only (400 without `dryRun: true`): parameter values to bind, by parameter name.
    - `media` object: Dry run only (400 without `dryRun: true`): media values to bind, by media parameter name.
    - `preset` string: Dry run only (400 without `dryRun: true`): the preset whose values the bind starts from.
  - TemplatePublishSlugRequest
    - `slug` string, required

## Response `200`

Dry run: the kernel's verdict on the document or the given inputs; nothing was stored.

- TemplateValidateResponse
  - `ok` boolean, required: True when the kernel found no problem.
  - `slug` string, nullable, required: The document's slug, or null when the document did not carry one.
  - `problems` TemplateProblem[], required: Every problem found, in the order the kernel's checks run; empty when `ok`.
    - `code` string, required: The problem's code: template_parse, template_parameter_undeclared, template_reference_misplaced, template_media_site, template_matte_stale, template_sample_missing, template_media_required, template_preset_unknown, template_values_invalid, template_media_kind_mismatch or payload_too_large.
    - `param` string: The parameter the problem names, when it names one.
    - `message` string, required

## Other responses

- `201`: The stored template.
- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `413`: Error
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)