> ## 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 or republish a template at a slug > Idempotent companion to `POST /v1/templates`. The URL slug is canonical (any `slug` in the body is ignored). If the template does not exist it is created and version 1 published (`201`). If it exists, a new version (n+1) is published and becomes current (`200`). Existing renders pin their own version and are unaffected. ## OpenAPI ````yaml /openapi.yaml put /v1/templates/{slug} openapi: 3.1.0 info: title: Craftkit API version: 1.0.0 description: > The Craftkit public REST API. Design templates with typed variables, render PDFs asynchronously, share and track them, and send them out for digital signature. ## Authentication Most endpoints authenticate with a **project API key** as a bearer token: ``` Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx ``` Keys come in `ck_live_` (production) and `ck_test_` (test) flavours. Embed iframe surfaces use a short-lived **embed session JWT** instead, and the admin provisioning endpoint uses the deployment-wide `CRAFTKIT_ADMIN_KEY`. Inbound webhooks (`/v1/hooks/*`) are not bearer-authed — they are verified by an HMAC signature header. ## Idempotency `POST /v1/templates/{slug}/render` and `POST /v1/signatures` accept an `Idempotency-Key` request header. Retrying with the same key returns the original resource instead of creating (and, for signatures, billing) a duplicate. ## Errors Application errors use a shared envelope: ```json { "error": { "code": "invalid_request", "message": "...", "issues": { } } } ``` A small number of admin/embed endpoints return a flatter shape (`{ "error": "invalid_credentials" }`); those are documented inline. servers: - url: https://api.craftkit.dev description: Production security: - bearerApiKey: [] tags: - name: Templates description: Create, list, fetch, republish, delete templates and enqueue renders. - name: Renders description: Poll render status, download PDFs, manage shares, email, and engagement. - name: Signatures description: >- Send rendered PDFs out for digital signatures via the signature service and track status. - name: Webhooks description: Inbound webhook receivers (HMAC-authenticated, not bearer-authed). - name: Embed description: Embed session minting, catalogs, builder templates, form submission. - name: Admin description: Org provisioning (deployment admin key only). - name: System description: Health and status. paths: /v1/templates/{slug}: parameters: - $ref: '#/components/parameters/TemplateSlug' put: tags: - Templates summary: Create or republish a template at a slug description: > Idempotent companion to `POST /v1/templates`. The URL slug is canonical (any `slug` in the body is ignored). If the template does not exist it is created and version 1 published (`201`). If it exists, a new version (n+1) is published and becomes current (`200`). Existing renders pin their own version and are unaffected. operationId: upsertTemplate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TemplateInput' example: name: Invoice description: Standard customer invoice manifest: variables: - key: customer.name label: Customer name dataType: text required: true loops: [] responses: '200': description: Existing template republished (new version). content: application/json: schema: $ref: '#/components/schemas/TemplateMutationResult' example: id: 7c9f0b2e-2b1a-4f3d-9c8e-1a2b3c4d5e6f slug: invoice currentVersionNumber: 4 manifest: variables: - key: customer.name label: Customer name dataType: text required: true loops: [] '201': description: Template did not exist and was created at this slug. content: application/json: schema: $ref: '#/components/schemas/TemplateMutationResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': description: | Slug occupied by a soft-deleted tombstone, or concurrent republishes could not allocate a version number. content: application/json: schema: $ref: '#/components/schemas/Error' examples: slugConflict: value: error: code: slug_conflict message: >- Slug 'invoice' is occupied by another (possibly deleted) template in this project. versionConflict: value: error: code: version_conflict message: >- Could not allocate a new version number due to concurrent republishes; retry. security: - bearerApiKey: [] components: parameters: TemplateSlug: name: slug in: path required: true description: The template slug (canonical identifier within the project). schema: type: string schemas: TemplateInput: type: object required: - name - manifest description: > Create/upsert body. `manifest` and `pageConfig` are validated against the shared schema package; `layout` is an optional explicit CanvasDocument. properties: name: type: string minLength: 1 maxLength: 120 slug: type: string maxLength: 120 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: >- Optional on create (auto-derived from name); ignored by PUT (URL is canonical). description: type: string maxLength: 280 layout: type: object additionalProperties: true description: >- Optional CanvasDocument contentJson; synthesized from the manifest when omitted. manifest: $ref: '#/components/schemas/VariableManifest' pageConfig: $ref: '#/components/schemas/PageConfig' TemplateMutationResult: type: object required: - id - slug - currentVersionNumber - manifest properties: id: type: string format: uuid slug: type: string currentVersionNumber: type: integer manifest: $ref: '#/components/schemas/VariableManifest' Error: type: object description: Shared application error envelope. required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string issues: description: Optional Zod flatten() / issues detail. example: error: code: invalid_request message: Request body did not match expected shape. VariableManifest: type: object required: - variables - loops properties: variables: type: array items: $ref: '#/components/schemas/VariableDefinition' loops: type: array items: $ref: '#/components/schemas/LoopDefinition' PageConfig: type: object properties: format: type: string enum: - A4 - A5 - Letter - Legal default: A4 orientation: type: string enum: - portrait - landscape default: portrait margin: type: string pattern: ^\d+(\.\d+)?(mm|cm|in|px)$ default: 20mm printBackground: type: boolean default: true VariableDefinition: type: object required: - key - label - dataType properties: key: type: string maxLength: 120 pattern: ^[a-zA-Z_][a-zA-Z0-9_.]*$ label: type: string maxLength: 120 dataType: $ref: '#/components/schemas/VariableDataType' required: type: boolean default: false defaultValue: $ref: '#/components/schemas/ScalarPrimitive' previewData: $ref: '#/components/schemas/ScalarPrimitive' format: type: string maxLength: 60 description: type: string maxLength: 280 LoopDefinition: type: object required: - key - label - itemFields properties: key: type: string maxLength: 120 pattern: ^[a-zA-Z_][a-zA-Z0-9_.]*$ label: type: string maxLength: 120 itemFields: type: array minItems: 1 items: $ref: '#/components/schemas/VariableDefinition' previewData: type: array maxItems: 10 items: type: object additionalProperties: true description: type: string maxLength: 280 VariableDataType: type: string enum: - text - longtext - number - currency - date - datetime - boolean - image - url - email ScalarPrimitive: type: - string - number - boolean - 'null' responses: BadRequest: description: Invalid JSON or request shape. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: Request body did not match expected shape. Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing Bearer token. securitySchemes: bearerApiKey: type: http scheme: bearer description: > Project API key (`ck_live_…` or `ck_test_…`) presented as a bearer token. For embed partner endpoints this is the partner secret key, which is the same credential type. ````