Upload and manage templates

New Endpoints in V5: We've improved our versioning system with a constant Template ID, making it easier to manage multiple versions, and added four new endpoints:

• PATCH /template: Update template metadata without re-uploading the template file.
• GET /templates: Retrieve a list of templates with filtering options.
• GET /templates/categories: Get the list of categories used by templates.
• GET /templates/tags: Get the list of tags used by templates.

Upload a template

Uploads a new template to the Carbone storage.

This endpoint supports optional metadata and advanced features like template versioning.

When versioning is enabled:

• A unique template ID is created, and a version ID representing the unique identifier (sha256) of the file. Both IDs can be used to Generate documents.
• Multiple versions of a template can be managed under the same Template ID.
• When a document is generated using a Template ID, Carbone will use the latest deployed version (based on the deployedAt timestamp parameter).

Request header

{
  // Required Your API token (string)
  "authorization"       : "Bearer API_TOKEN",
  // Required Content-type 
  "content-type"        : "multipart/form-data", // or "application/json" (solution 2)
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Request body

The body request can be either:

• A FormData object that contains the template as a Buffer or as a Blob. The file should be assigned to the attribute template. The request header must include {"content-type": "multipart/form-data"}.
• A JSON object that contains the template as a base64 String { "template" : "pure base64 or a base64 data-URI"}. The request header must include {"content-type": "application/json" }.

Parameter	Type	Required	Description
template	File	Yes	The template file to upload. This can be provided either as a base64-encoded string or as multipart/form-data. Ensure that the template field is the last element in the request body to avoid any issues with the request.
versioning	Boolean	False	Template versioning is enabled if: - versioning is true → a new Template ID is generated. - versioning is true and the id field is provided → the new template is added to the existing Template ID’s version history. Template versioning is disabled if: - versioning is false/undefined, and if the id field is undefined.
id	String	False	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.
name	String	False	Template name.
comment	String	False	Template comment.
tags	Array[String]	False	List of tags.
category	String	False	Group multiple templates into categories, similar to folders.
samples	Array[Object]	False	Sample input data.
deployedAt	Integer	False	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.
expireAt	Integer	False	Delete the template at the specified time. The expireAt value must be a UTC Unix timestamp. Values ≥ 42000000000 (year 3300) are treated as 'now'. Future timestamps are not allowed.

Responses

On success (status code 200) , the response body returns a JSON containing identifiers (id and versionId), file type, size, and creation timestamp. For backward compatibility (versioning field disabled or undefined), it returns only the field templateId, SHA-256 hash of the template file.

{
  "success": true,
  "data": {
    "id": "TEMPLATE_ID (64-bit String)",
    "versionId": "VERSION_ID (Sha256 String)",
    "type": "FILE_TYPE",
    "size": FILE_SIZE_IN_BYTES,
    "createdAt": UTC_UNIX_TIMESTAMP
  }
}

On error, the following responses can be returned:

	Status Code	Body
	400	{ "success" : false, "error" : "Cannot store template" }
	400	{ "success" : false, "error" : "Content-Type header should be multipart/form-data or application/json" }
	400	{ "success" : false, "error" : "The 'X' field must be sent before the 'template' file field in the form data." }
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	413	{ "success" : false, "error" : "Template too large, the file size limit is X Bytes"}
	415	{ "success" : false, "error" : "Template format not supported" }
	422	{ "success" : false, "error" : ""template" field is empty" }
	500	{ "success" : false, "error" : "Database error." }
	500	{ "success" : false, "error" : "Server Error."}

Curl Example

Example 1 - Add a template with the absolute file path

curl  --location --request POST 'https://api.carbone.io/template' \
      --header 'carbone-version: 5' \
      --header 'Expect:' \
      --header 'Content-Type: multipart/form-data' \
      --header 'Authorization: Bearer API_TOKEN' \
      --form 'template=@"ABSOLUTE_FILE_PATH"'

Example 2 - Add a template with the file as a base64 String

curl  --location --request POST 'https://api.carbone.io/template' \
      --header 'carbone-version: 5' \
      --header 'Expect:' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer API_TOKEN' \
      --data-raw '{ "template": "BASE64_STRING" }'

Download a template

Fetches a specific template or version of a template from the Carbone storage. It supports:

• Retrieving the latest deployed version of a template using the templateId, as well as versions via versionId.
• Downloading JSON data samples associated with templates or specific versions, which are used in the Studio for testing and development purposes. The URL PATH must be specified as /template/{templateId}_sample.json or /template/{versionId}_sample.json to download associated data samples.

Request header

{
  // Required Your API token (string)
  "authorization" : "Bearer API_TOKEN",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Response body

On success, the Stream of the template file is returned.
On error, a JSON is returned with details of the problem.

	Status Code	Body
	200	File stream
	400	{ "success" : false, "error" : "Invalid templateId"}
	400	{ "success" : false, "error" : "Cannot retrieve template"}
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	404	{ "success" : false, "error" : "Template not found"}
	500	{ "success" : false, "error" : "Server Error."}

Curl example

curl  --location --request GET 'https://api.carbone.io/template/TEMPLATE_ID' \
      --header 'carbone-version: 5' \
      --header 'Authorization: Bearer API_TOKEN' \
      -o 'FILENAME.docx'

Delete a template

Deletes either the template including all its versions, when using a template Id, or a specific version of a template when using a version Id.

The deletion process involves setting an expireAt timestamp parameter, marking the template for garbage collection after a predefined delay (default: 24 hours). This approach is equivalent to calling PATCH /template/{id} with expireAt = NOW.

Request header

{
  // Required Your API token (string)
  "authorization" : "Bearer API_TOKEN",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Response

A JSON is returned as body response.
On success, a status code 200 is returned.

	Status Code	Body
	200	{ "success" : true }
	400	{ "success" : false, "error" : "Invalid templateId"}
	400	{ "success" : false, "error" : "Cannot delete template"}
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	404	{ "success" : false, "error" : "Template not found"}
	500	{ "success" : false, "error" : "Database error." }
	500	{ "success" : false, "error" : "Server Error."}

Curl example

curl  --location --request DELETE 'https://api.carbone.io/template/TEMPLATE_ID' \
      --header 'carbone-version: 5' \
      --header 'Authorization: Bearer API_TOKEN'

Patch a Template

Updates specific metadata and attributes of an existing template identified by its template ID, or version ID. It allows:

• 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.

Request header

{
  // Required Your API token (string)
  "authorization"       : "Bearer API_TOKEN",
  // Required Content-type 
  "content-type"        : "application/json",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Request body

The request body should be a JSON object with the following optional properties:

Parameter	Type	Required	Description
name	String	False	Template name.
comment	String	False	Template comment.
tags	Array[String]	False	List of tags.
category	String	False	Group multiple templates into categories, similar to folders.
deployedAt	Integer	False	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.
expireAt	Integer	False	Delete the template at the specified time. The expireAt value must be a UTC Unix timestamp. Values ≥ 42000000000 (year 3300) are treated as 'now'. Future timestamps are not allowed.

Response

A JSON is returned as body response.
On success, a status code 200 is returned.

	Status Code	Body
	200	{ "success" : true }
	400	{ "success" : false, "error" : "Invalid templateId"}
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	404	{ "success" : false, "error" : "Template not found"}
	500	{ "success" : false, "error" : "Database error."}
	500	{ "success" : false, "error" : "Server Error."}

Curl

curl --location --request PATCH 'https://api.carbone.io/template/{templateId-or-versionId}' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw '{
  "name": "Updated Template Name",
  "comment": "Updated comment",
  "category": "Folder1",
  "tags": ["invoice", "contract", "v2"],
  "expireAt": 0,
  "deployedAt": 1625097600
}'

List Templates

Retrieves a list of templates from the Carbone storage. It supports filtering and pagination to manage large numbers of templates. The endpoints allows:

• Filtering: Filter templates by ID, version ID, and category to narrow down results based on specific criteria.
• Search: Utilize search for template names and exact matches for IDs and version IDs to quickly locate desired templates.
• Sorting: By default, the endpoint returns all deployed templates, sorted by creation date in descending order, excluding any that have expired. Changing the sorting order is not available for the moment.
• Pagination: This endpoint uses cursor-based pagination to manage large result sets. Each response includes two properties to control pagination:
  • hasMore (boolean): Indicates whether additional templates are available beyond the current set. If false, the current response contains the last page of results.
  • nextCursor (string): If hasMore is true, this value specifies the cursor to use in the next request to fetch the subsequent batch of templates. Include it as a query parameter ?cursor={value} in your follow-up request.

Request header

{
  // Required Your API token (string)
  "authorization" : "Bearer API_TOKEN",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Query Parameters

The endpoint supports filtering by various criteria such as: template Id, version ID, and category, offering flexibility to retrieve specific subsets of templates. Additionally, it supports fuzzy search in template names and exact matches on IDs and version IDs, enhancing discoverability.

Parameter	Type	Description
id	String	Filter by template ID.
versionId	String	Filter by version ID.
category	String	Filter by category.
origin	Integer	Filter templates by their upload origin. - 0: Templates uploaded via the API. - 1: Templates uploaded via the Studio.
includeVersions	Boolean	Set true to list all versions for a specific template ID. By default equals to false.
search	String	Search in template name (fuzzy search), version ID (exact match), or template ID (exact match).
limit	Integer	Limit the number of items. By default equals to 100.
cursor	String	A cursor to use in pagination. The cursor defines your place in the list for fetching the next set of results.

Response

On Success (status code 200), the response will include a list of templates with their metadata.

{
    "success": true,
    "data": [
    {
      "id": "",
      "versionId": "",
      "deployedAt": UTC_UNIX_TIMESTAMP,
      "createdAt": UTC_UNIX_TIMESTAMP,
      "expireAt": UTC_UNIX_TIMESTAMP,
      "size": FILE_SIZE_IN_BYTES,
      "type": "FILE_TYPE",
      "name": "FILE_NAME",
      "category": "",
      "comment": "",
      "tags": [],
      "origin": 0
    }
  ],
  "hasMore": true,
  "nextCursor": "CURSOR_HASH"
}

On Error

	Status Code	Body
	400	{ "success" : false, "error" : "Invalid search filters."}
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	500	{ "success" : false, "error" : "Database error."}
	500	{ "success" : false, "error" : "Server Error."}

Curl example

curl --location --request GET 'https://api.carbone.io/templates' \
      --header 'carbone-version: 5' \
      --header 'Authorization: Bearer API_TOKEN'

List Categories

Retrieve a list of all categories used in templates. Categories function similarly to folders, allowing you to group and organize your templates effectively (e.g. "customer-x", "project-2026", "finances").

Practical Usage:

• Uploading a Template: When uploading a template, you can specify a category.
• Updating a Template: You can add or modify the category when updating template metadata.
• Listing Templates: You can filter templates by category to quickly find that are relevant to a specific function or type.

Request header

{
  // Required Your API token (string)
  "authorization" : "Bearer API_TOKEN",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Response

On Success (status code 200), the response will include a list of folders used in templates.

{
  "success":true,
  "data":[
    { "name":"folder1" },
    { "name":"customer2" }
  ]
}

On Error

	Status Code	Body
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	500	{ "success" : false, "error" : "Database error."}
	500	{ "success" : false, "error" : "Server Error."}

Curl Example

curl  --location --request GET 'https://api.carbone.io/templates/categories' \
      --header 'carbone-version: 5' \
      --header 'Authorization: Bearer API_TOKEN'

List Tags

List all tags currently used in templates.

Tags are labels that you can attach to your templates for better organization. They help you categorize templates based on different criteria, such as the type of document (e.g., "invoice", "contract") or the version of the template (e.g., "v19.2.1").

Practical Usage:

• Uploading a Template: When uploading a template, you can specify tags to categorize it.
• Updating a Template: You can add or modify tags when updating template metadata.
• Listing Templates: This allows you to see which tags are assigned to each template, helping you to better organize templates. It is not possible to filter templates based on tags for the moment.

Request header

{
  // Required Your API token (string)
  "authorization" : "Bearer API_TOKEN",
  // OPTIONAL Carbone-Version (string)
  "carbone-version"     : "5",
}

Response

On Success (status code 200), the response will include a list of tags used in templates.

{
  "success":true,
  "data":[
    { "name":"contract" },
    { "name":"invoice" },
    { "name":"tag3" },
    { "name":"v8.2.1" }
  ]
}

On Error

	Status Code	Body
	401	{ "success" : false, "error" : "Unauthorized, please provide a correct API key on the "Authorization" header"}
	500	{ "success" : false, "error" : "Database error."}
	500	{ "success" : false, "error" : "Server Error."}

Curl Example

curl  --location --request GET 'https://api.carbone.io/templates/tags' \
      --header 'Authorization: Bearer API_TOKEN' \
      --header 'carbone-version: 5'