CAcarbone
Template

Update template metadata.

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 (64-bit format), Carbone patches the currently deployed version of that template.
  • With a 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.

patch/template/{templateId-or-versionId}

Request

Path parameters

templateId-or-versionIdstring required

Unique identifier of the template or version ID

Headers

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

Carbone API major version to use. Only a major version can be specified: it automatically includes all future minor versions and patches.

  • 5: latest version, recommended.
  • 4: default when the header is not provided.
  • 3: legacy.
  • staging: not intended for production environments.

It is strongly recommended to always set this header explicitly to avoid unexpected behavior. See API versioning documentation

Request body

idstring

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.

namestring

Template name, 200 characters maximum.

commentstring

Template comment, 200 characters maximum.

categorystring

Group multiple templates into categories, similar to folders. 200 characters maximum.

tagsstring[]

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.

expireAtinteger

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.

deployedAtinteger

When generating a document with a 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

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.

successboolean

Changes

No recorded changes to this operation across all 1 revision of this API.