---
title: "Upload a template."
method: POST
path: "/template"
tags: ["Template"]
---

# Upload a template.

`POST /template`

## Request

- Base URL: `https://api.carbone.io`
- URL: `https://api.carbone.io/template`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/carbone/apis/carbone-api/docs/template/post.ts> (a function with typed inputs; its response is checked against the schema)

Uploads a new template to the Carbone storage, supporting optional metadata and advanced features like template versioning. When versioning is enabled, multiple versions of a template can be managed under the same template `id`, and specific versions can be deployed using the `deployedAt` parameter.

### Features
- Metadata Support: Attach metadata such as name, comment, and tags to the template for better organization and retrieval.
- Template Versioning: By enabling the `versioning` parameter, users can manage multiple versions of a template, allowing for a history of changes and rollbacks.
- Deployed Version Control: Specify which version of a template is deployed using the `deployedAt` timestamp.
- Sample Data: Attach sample input data to templates to facilitate testing and development in the Carbone Studio environment.

### Backward Compatibility
For backward compatibility, if the `versioning` parameter is not provided or is set to false, the endpoint behaves as it did in previous versions. This means it does not enable the new versioning features and maintains the returned body request `{ "success": true, "data": { "templateId": "SHA256", "templateExtension": "docx" }}` that older applications expect.

### Use Cases
Ideal for template management, including maintaining multiple versions of a document template, automating document generation workflows with precise control over deployments, and enhancing template metadata for better search and retrieval.

## Headers

- `carbone-version` '5' | '4' | '3' | 'staging', required

## Request body

- object
  - `id` string: [Template ID](https://carbone.io/documentation/developer/http-api/introduction.html#template-id) (64-bit format). If the `id` is provided, the new template is added to the existing Template ID’s version history. If the id field is left empty, a new Template ID is generated. Providing a Version ID (SHA256 format) is not allowed and will result in an API error.
  - `versioning` boolean: Template versioning is **enabled** if: - `versioning` is "true" → a new [Template ID](https://carbone.io/documentation/developer/http-api/introduction.html#template-id) is generated. - `versioning` is "true" and the `id` field is provided → the new template is added to the existing [Template ID](https://carbone.io/documentation/developer/http-api/introduction.html#template-id)’s version history. Template versioning is **disabled** if: - `versioning` is "false" or "undefined", and if the `id` field is "undefined".
  - `template` string, required
  - `name` string: Template name, 200 characters maximum.
  - `comment` string: Template comment, 200 characters maximum.
  - `category` string: Group multiple templates into categories, similar to folders. 200 characters maximum.
  - `tags` string[]: List of tags. Duplicates are removed and the list is returned sorted alphabetically. The whole list is limited to 100 characters, which is about 8 tags of 9 characters.
  - `sample` object[]: Sample input data used in Carbone Studio for testing and development. A single object with the optional properties `data`, `complement`, `translations` and `enum`.
    - `data` object: JSON dataset merged into the template with `{d.}` tags.
    - `complement` object: Extra data accessible in the template with `{c.}` tags.
    - `translations` object: Localization dictionary used with `{t()}` tags.
    - `enum` object: List of enumerations for use with the `convEnum` formatter.
  - `expireAt` integer: Schedule the template for deletion, as a UTC Unix timestamp in seconds. Nothing changes until that time. After it, the template is no longer listed, cannot be downloaded, and generating a document with it returns `404 Template not found`. The file itself is deleted later, once the storage retention delay has passed. `0` (default) means the template never expires.
  - `deployedAt` integer: When generating a document with a [Template ID](https://carbone.io/documentation/developer/http-api/introduction.html#template-id), Carbone uses the most recent deployedAt version. The deployedAt value must be a UTC Unix timestamp; values ≥ 42000000000 (year 3300) are interpreted as 'NOW'. Future values are not allowed.
  - `origin` integer: Where the template comes from, used to filter the template list. Set at upload time only: it cannot be changed afterwards. - `0`: API (default) - `1`: Studio - `2`: Salesforce - `3`: Odoo - `4`: HubSpot

## Response `200`

On success, returns metadata about the uploaded template. When versioning is enabled, it returns a comprehensive object containing identifiers (`id` and `versionId`), file type, size, and creation timestamp. When versioning is disabled or undefined (`versioning` and `id` fields not provided), it returns only `templateId` (SHA-256 hash of the template file) and `templateExtension`.

- object
  - `success` boolean
  - `data` union
    - object
      - `id` string: Template ID.
      - `versionId` string: Version ID of the template.
      - `type` string: Type of the template file.
      - `size` integer: Size of the template file in bytes.
      - `createdAt` integer: UTC Unix timestamp of when the template was created.
      - `deployedAt` integer: UTC Unix timestamp of when the template version was deployed. Returns 0 if not deployed. This is the value saved by Carbone: when the request asked to deploy now, it is the current time.
    - object
      - `templateId` string: SHA-256 hash of the template file (for backward compatibility).
      - `templateExtension` string: Detected file extension of the template (e.g. `docx`).

## Other responses

- `400`: The request body could not be accepted: a rejected metadata value, invalid sample data, or a malformed upload.
- `401`: Unauthorized, please provide a correct API key on the `Authorization` header. The API key is available on your Carbone account: https://account.carbone.io.
- `413`: JSON (base64) mode only: the template, or the template and sample data together, exceed the size limit. In multipart/form-data mode, an oversized file returns a `400` error.
- `415`: Template format not supported, it must be an XML-based or Text-based document.
- `422`: The `template` field is empty on the body request
- `500`: Server or Database Error.

## Changes

- **2026-11-06** `c06cc573e3b0`: 5 breaking, 8 warning, 18 info
  - the `carbone-version` request header's property undefined was restricted to a list of enum values
  - the `header` request parameter `carbone-version` was restricted to a list of enum values
  - the `expireAt` request property format changed from no format to `int64` (media type: multipart/form-data)
  - the `expireAt` request property format changed from no format to `int64` (media type: application/json)
  - …27 more
- **2026-06-13** `fb25492a25ce`: 2 warning, 3 info
  - removed the request property `samples` (media type: multipart/form-data)
  - removed the request property `samples` (media type: application/json)
  - added the new optional request property `sample` (media type: multipart/form-data)
  - added the new optional request property `sample` (media type: application/json)
  - …1 more

[Operation history](https://skmtc.dev/carbone/apis/carbone-api/changes/template/post.md)

---

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