--- title: "Update template metadata." method: PATCH path: "/template/{templateId-or-versionId}" tags: ["Template"] --- # Update template metadata. `PATCH /template/{templateId-or-versionId}` ## Request - Base URL: `https://api.carbone.io` - URL: `https://api.carbone.io/template/{templateId-or-versionId}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Updates specific metadata and attributes of an existing template identified by its ID. This endpoint is crucial for managing the lifecycle and details of templates without the need to re-upload the template file. It allows for precise control over template metadata, versioning, and deployment states. ### Features - Metadata Management: Modify template metadata such as name, comment, and tags for improved organization and searchability. - Version Deployment: Update the `deployedAt` field to control which version of a template is actively deployed, ensuring that the correct template version is used in document generation processes. - Lifecycle Control: Manage the template's lifecycle by updating the expiration timestamp, allowing for fine-grained control over template availability. ### Which version is patched The identifier in the URL decides which version is patched: - With a [Template ID](https://carbone.io/documentation/developer/http-api/introduction.html#template-id) (64-bit format), Carbone patches the **currently deployed version** of that template. - With a [Version ID](https://carbone.io/documentation/developer/http-api/introduction.html#version-id) (SHA256 format), Carbone patches that exact version. ### Use Cases Updating template metadata to reflect changes in document usage or categorization, switching between template versions for deployment to support different document generation needs, and managing template lifecycle by setting expiration dates to automatically retire outdated templates. ## Path parameters - `templateId-or-versionId` string, required ## 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) the patched version belongs to. Providing a Version ID (SHA256 format) is not allowed and will result in an API error. Changing this value moves the version to another Template ID. Target the version with its **Version ID** in the URL, otherwise you move the version that is currently deployed, and the original Template ID falls back to its next most recent version, or stops resolving if it has none left. An error is returned if the move creates a `deployedAt` conflict with the version already deployed under the destination Template ID. - `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. - `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. Send `0` to cancel a scheduled deletion and make the template permanent again. Omit the field to leave the current expiration untouched. - `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. ## Response `200` Template metadata updated successfully. The response always includes `versionId`, plus the fields provided in the request body. `deployedAt` is the value saved by Carbone: when the request asked to deploy now, it is the current time. - object - `success` boolean - `data` object - `versionId` string: Version ID of the updated template. - `name` string: Template name, returned if updated in this request. - `comment` string: Template comment, returned if updated in this request. - `tags` string[]: List of tags, returned if updated in this request. - `category` string: Category name used to group templates, returned if updated in this request. - `deployedAt` integer: UTC Unix timestamp saved for the version, returned if updated in this request. When the request asked to deploy now, it is the current time. - `expireAt` integer: UTC Unix timestamp at which the template stops being returned by the API, returned if updated in this request. `0` means the template never expires. ## Other responses - `400`: The request could not be accepted: a rejected metadata value, a field that cannot be patched, an empty body, or an invalid ID in the URL. - `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. - `404`: The template is not found - `500`: Server or Database Error. - `501`: Carbone On-Premise only: this endpoint needs the template database, and the server runs in stateless mode (no database). ## Changes - **2026-11-06** `c06cc573e3b0`: 2 breaking, 4 warning, 7 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 `category` request property's maxLength was set to `200` - the `comment` request property's maxLength was set to `200` - …9 more - **2026-06-13** `fb25492a25ce`: 1 info - added the optional property `data` to the response with the `200` status [Operation history](https://skmtc.dev/carbone/apis/carbone-api/changes/template/:templateId-or-versionId/patch.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)