HTTP API

Upload and manage templates

Manage templates | Get your awesome documents with this simple HTTP API

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:

Upload a template

/template

Uploads a new template to the Carbone storage.

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

When versioning is enabled:

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:

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

/template/{templateId-or-versionId}

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

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

/template/{templateId-or-versionId}

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

/template/{templateId-or-versionId}

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

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

/templates

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

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

/templates/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:

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

/templates/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:

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'