CAcarbone
Template

Upload a template.

Changed on

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.

post/template

Request

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

versioningboolean

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" or "undefined", and if the id field is "undefined".
templatestring required
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.

0 (default) means the template never expires.

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.

origininteger

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

Example request

{
  "template": "Base64-encoded Template File contents, supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML or an XML file",
  "tags": [
    "invoice",
    "contract",
    "v2"
  ],
  "sample": [
    {
      "data": {},
      "complement": {},
      "translations": {},
      "enum": {}
    }
  ]
}

Response

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.

successboolean

Changes

  • c06cc573e3b0Revision changes
    • breaking

      the carbone-version request header's property undefined was restricted to a list of enum values

    • breaking

      the header request parameter carbone-version was restricted to a list of enum values

    • breaking

      the request property format changed from no format to int64 (media type: multipart/form-data)

    • breaking

      the request property format changed from no format to int64 (media type: application/json)

    • breaking

      added subschema #1 subschema #2 to the response property oneOf list for the response status

    • warning

      the request property's maxLength was set to 200 (media type: multipart/form-data)

    • warning

      the request property's maxLength was set to 200 (media type: application/json)

    • warning

      the request property's maxLength was set to 200 (media type: multipart/form-data)

    • warning

      the request property's maxLength was set to 200 (media type: application/json)

    • warning

      the request property's maxLength was set to 200 (media type: multipart/form-data)

    • warning

      the request property's maxLength was set to 200 (media type: application/json)

    • warning

      the request property's min was set to 0.00 (media type: multipart/form-data)

    • warning

      the request property's min was set to 0.00 (media type: application/json)

    • info

      added the new optional request property (media type: multipart/form-data)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new enum value 3 to the header request parameter carbone-version

    • info

      added the new enum value 4 to the header request parameter carbone-version

    • info

      added the new enum value 5 to the header request parameter carbone-version

    • info

      added the new enum value staging to the header request parameter carbone-version

    • info

      for the header request parameter carbone-version, the type was generalized from integer to string, and format from int32 to no format

    • info

      the request property // became optional (media type: multipart/form-data)

    • info

      the request property // became optional (media type: application/json)

    • info

      the request property // became optional (media type: multipart/form-data)

    • info

      the request property // became optional (media type: application/json)

    • info

      the request property // became optional (media type: multipart/form-data)

    • info

      the request property // became optional (media type: application/json)

    • info

      the request property // became optional (media type: multipart/form-data)

    • info

      the request property // became optional (media type: application/json)

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed subschema #1 subschema #2 from the response property oneOf list for the response status

  • fb25492a25ceRevision changes
    • warning

      removed the request property (media type: multipart/form-data)

    • warning

      removed the request property (media type: application/json)

    • info

      added the new optional request property (media type: multipart/form-data)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the optional property // to the response with the status