Document

Generate a document.

Changed on Nov 6, 2026

Renders a document by merging a template with JSON data, or converts a pre-uploaded document to another format:

Document generation - merge a Carbone template (using {d.field} tags) with a JSON dataset to produce a customised document.
Document conversion - omit data (from carbone-version: 5) and pass a convertTo value to convert a pre-uploaded document (DOCX, XLSX, PPTX, HTML, ODT, ODS, ODP, ODG…) to another format. To convert without pre-uploading, use POST /render/template with a base64-encoded document in the body instead.

Features

Dynamic Document Generation: Create documents by merging pre-designed templates with dynamic JSON data, ensuring consistency and customization in generated documents.
Version Support: Utilize either a template ID or a specific version ID to control which version of a template is used for rendering, allowing for precise document generation.
Output Format Flexibility: Generate documents in various formats by specifying output types, catering to diverse business and compliance needs.
Constant Template ID: Multiple versions of a template can be associated with a single Template ID. Carbone checks the deployedAt timestamp to determine which version of the template is actively deployed. The version with the most recent deployedAt timestamp is selected for document generation.

Notes

Direct download - Use the download query parameter and set it to true to receive the file as a direct stream, or false to receive a renderId for a separate GET /render/{renderId} download call.
Converter - When the output format differs from the template format, set converter to L (LibreOffice, default), I (Carbone ICE, the fastest for DOCX/ODT to PDF), C (Chromium, for HTML) or O (OnlyOffice). See the converter field in the request body.

post/render/{templateId-or-versionId}

Request

Base URL
https://api.carbone.io
Auth
HTTP bearer
TypeScript
https://skmtc.dev/carbone/apis/carbone-api/docs/render/:templateId-or-versionId/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

templateId-or-versionIdstring required

Unique identifier of the template or version ID

Query parameters

downloadboolean

Controls how the document is returned.

true: returns the document directly as a file stream (the Content-Type reflects the output format). The file is not stored on Carbone servers and no renderId is issued, so there is no need to call GET /render/{renderId}.
false: returns a JSON object with a renderId; use GET /render/{renderId} to download the file in a second call.

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

carbone-webhook-urlstring

Example:https://my-server.com/carbone-webhook

URL that Carbone calls (HTTP POST) when an asynchronous render or conversion finishes. Providing it enables asynchronous mode, which raises the rendering timeout to 5 minutes.

carbone-webhook-header-authorizationstring

Custom header forwarded on the webhook call only. It follows the carbone-webhook-header-<name> pattern, where any header <name> can be sent to your webhook (authorization is the most common). For the authorization header, this overrides carbone-egress-header-authorization for webhook calls.

carbone-egress-header-authorizationstring

Sets the authorization header Carbone sends on all egress traffic for this render: webhook calls, dynamic image URLs, and files fetched by appendFile. Example: carbone-egress-header-authorization: my-secret makes Carbone send authorization: my-secret on each outbound request. Only the authorization header can be customized, and the value must be shorter than 512 characters. For webhook calls, carbone-webhook-header-authorization overrides this value (webhook only).

Request body

converter'L' | 'O' | 'C' | 'I'

Converter engine to use when a document format change is required (not only when convertTo is "pdf"). If omitted, LibreOffice (L) is used. See https://carbone.io/documentation/developer/http-api/generate-reports.html#converters

L LibreOffice (default): DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF. Best balance between performance and document compatibility, and the only converter supporting all PDF options.
I Carbone ICE (Instant Converter Engine): DOCX, ODT to PDF. The fastest converter, 3x to 300x faster than LibreOffice, OnlyOffice, or MS Word: Carbone draws the PDF itself, with no office suite involved. Only the Security and Watermark PDF options are supported. ODT to PDF is in beta. It can also be enabled per template with the {o.converter=I} tag. See limitations: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations
C Chromium: HTML and XHTML to PDF, PNG, JPG/JPEG and WebP. SVG to PDF, PNG, JPG/JPEG and WebP. Image output options: PixelWidth, PixelHeight, FullPage, Scale, Quality. High-fidelity HTML conversion with full CSS support. JavaScript is disabled. Only the Security and Watermark PDF options are supported. 100 MB maximum document size.
O OnlyOffice: DOCX, XLSX, PPTX to PDF. Alternative for office documents. Only the Security and Watermark PDF options are supported. From v5.15.0, Carbone ICE is recommended instead of OnlyOffice for DOCX to PDF.

templatestring

Optional - Upload a template in base64 format. When used, the URL should be /render/template.

timezonestring

Optional - Convert document dates to a timezone. The default timezone is Europe/Paris. The date must be chained with the :formatD formatter, for instance {d.date:formatD(YYYY-MM-DD HH:MM)}. List of accepted timezones (Column TZ identifier): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

langstring

Optional - Locale of the generated document, it will be used for translation {t()}, formatting numbers with :formatN, and currencies :formatC. List of supported locales: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js

complementobject

Optional - Object|Array, extra data accessible in the template with {c.} instead of {d.}

variableStrstring

Optional - Predefine alias, related documentation: https://carbone.io/documentation/design/substitutions/aliases.html#alias

reportNamestring

Optional - Static or dynamic file name returned in the content-disposition header when the generated report is fetched with GET /render/{renderId}. The output extension is appended automatically, so do not include it. Multiple Carbone tags are accepted, such as {d.type}-{d.date}

enumobject

Optional - List of enumerations, use it in reports with convEnum formatters, documentation: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html#convenum-type

translationsobject

Optional - When the report is generated, all text between {t( )} is replaced with the corresponding translation. The lang option is required to select the correct translation. Learn more: https://carbone.io/documentation/design/advanced-features/translations-i18n.html

currencySourcestring

Optional - Currency source coming from your JSON data. The option is used by formatC to convert the currency based on the currencyTarget and currencyRates. Learn more: https://carbone.io/documentation/design/formatters/currency.html#formatc-precisionorformat-targetcurrency

currencyTargetstring

Optional - Target currency when the document is generated. The option is used by formatC to convert the currency based on the currencySource and currencyRates. Learn more: https://carbone.io/documentation/design/formatters/currency.html#formatc-precisionorformat-targetcurrency

currencyRatesobject

Optional - Currency exchange rates for conversions from currencySource to currencyTarget. Learn more: https://carbone.io/documentation/design/formatters/currency.html#formatc-precisionorformat-targetcurrency

hardRefreshboolean

Optional - If true, the report content is refreshed at the end of the rendering process. It is mostly used to refresh a table of content. It also forces a conversion when the output format is the same as the template format (for example XLSX to XLSX), to recompute spreadsheet formulas.

batchSplitBystring

Optional - Generate multiple reports with one template and an array of data, one report per object. "d" when data is itself an array of objects, or "d.myArray" to select a direct child array of data. Requires the carbone-webhook-url header (asynchronous mode) and a non-empty array of at most 100 objects on Carbone Cloud. Learn more: https://carbone.io/documentation/developer/http-api/generate-reports.html#batch-processing

batchOutput'zip' | 'pdf'

Optional (v5+) - Output file type for batch processing. zip (default) returns an archive of all the reports. pdf returns a concatenation of the generated PDFs, and requires convertTo to be pdf.

batchReportNamestring

Optional - Name of each file inside the ZIP batch export, Carbone tags accepted (e.g. report-{d.id}). Ignored when batchOutput is pdf. Used together with batchSplitBy. From v5.14.0, an index is appended to every file (report_1.pdf, report_2.pdf) as soon as the first two reports resolve to the same name.

preReleaseFeatureIninteger

Optional - Pre-release feature level for this render only. Only features and fixes introduced up to the given tag are applied, higher tags stay disabled. It overrides the server default, and can itself be overridden by the tag set in the template. Learn more: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features

failOnstring[]

Optional (v5.15.0+). Array of conditions that stop the render and return an error. The value must be an array of strings. An unknown value is rejected with an explicit error.

IMAGE_URL_ERROR: an image that cannot be downloaded from its URL stops the report, instead of being replaced with the broken-image placeholder. An empty or undefined image value is skipped, and the report is generated as usual. Only images coming from a URL are concerned. Base64 images, barcodes and charts keep their current behavior. It also applies to the Chromium converter, for PDF and image outputs: an image of an HTML page, or a resource of an SVG file, that cannot be downloaded stops the conversion. Learn more: https://carbone.io/documentation/developer/http-api/generate-reports.html#fail-on

Example request

{
  "convertTo": "pdf",
  "converter": "L",
  "template": "base64-encoded-template",
  "timezone": "Europe/Paris",
  "lang": "fr-fr",
  "complement": {},
  "variableStr": "{#def = d.id}",
  "reportName": "{d.date}",
  "enum": {},
  "translations": {
    "fr": {
      "one": "un"
    },
    "es": {
      "one": "uno"
    }
  },
  "currencySource": "EUR",
  "currencyTarget": "USD",
  "currencyRates": {
    "EUR": 1,
    "USD": 1.2
  },
  "batchSplitBy": "d.items",
  "batchOutput": "zip",
  "batchReportName": "report-{d.id}",
  "preReleaseFeatureIn": 5000000,
  "failOn": [
    "IMAGE_URL_ERROR"
  ]
}

Response

On success, by default a JSON response containing the renderId is returned. If the query parameter download=true is used, the response body is the converted/generated file stream and the Content-Type reflects the output format.

successboolean

messagestring

Returned only in asynchronous mode (carbone-webhook-url header set). The webhook URL is then called with { "success": true, "data": { "renderId": "..." } } once the document is generated.

Example response

{
  "data": {
    "renderId": "MTAuMjAuMjEuMTAgICAg.pdf"
  },
  "message": "A render ID will be sent to your callback URL when the document is generated"
}

Changes

Nov 6, 2026c06cc573e3b0 Revision 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
  for the query request parameter download, default value was changed from true to false
- breaking
  request property was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property /// was restricted to a list of enum values
- breaking
  request property was restricted to a list of enum values
- breaking
  the /// request property type changed from number to integer
- breaking
  the /// request property type changed from number to integer
- warning
  the /// request property's max was set to 100.00
- warning
  the /// request property's min was set to 0.00
- info
  added the new optional header request parameter carbone-egress-header-authorization
- info
  added the new optional header request parameter carbone-webhook-header-authorization
- info
  added the new optional header request parameter carbone-webhook-url
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property ///
- info
  added the new optional request property
- info
  added the new optional request property
- 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
- info
  the request property default value zip was added
- info
  the request property default value L was added
- info
  the request property default value 100 was removed
- info
  added the new 0.00 enum value to the request property ///
- info
  added the new 0.00 enum value to the request property ///
- info
  added the new 0.00 enum value to the request property ///
- info
  added the new 1.00 enum value to the request property ///
- info
  added the new 1.00 enum value to the request property ///
- info
  added the new 1.00 enum value to the request property ///
- info
  added the new 1200.00 enum value to the request property ///
- info
  added the new 15.00 enum value to the request property ///
- info
  added the new 150.00 enum value to the request property ///
- info
  added the new 16.00 enum value to the request property ///
- info
  added the new 17.00 enum value to the request property ///
- info
  added the new 2.00 enum value to the request property ///
- info
  added the new 2.00 enum value to the request property ///
- info
  added the new 2.00 enum value to the request property ///
- info
  added the new 20.00 enum value to the request property ///
- info
  added the new 3.00 enum value to the request property ///
- info
  added the new 3.00 enum value to the request property ///
- info
  added the new 300.00 enum value to the request property ///
- info
  added the new 4.00 enum value to the request property ///
- info
  added the new 4.00 enum value to the request property ///
- info
  added the new 600.00 enum value to the request property ///
- info
  added the new 75.00 enum value to the request property ///
- info
  added the new C enum value to the request property
- info
  added the new I enum value to the request property
- info
  added the new L enum value to the request property
- info
  added the new O enum value to the request property
- info
  added the new pdf enum value to the request property
- info
  added the new zip enum value to the request property
- info
  request property list-of-types was widened by adding types array to media type application/json
- info
  the ///// request property's minLength was decreased from 1 to 0
- info
  added the non-success response with the status
- info
  added the optional property to the response with the status
Jun 13, 2026fb25492a25ce Revision changes
- breaking
  for the query request parameter download, default value was changed from false to true
- breaking
  the request property type changed from string to no type
- info
  added the new optional request property
- info
  added subschema #1 subschema #2 to the request property oneOf list
- info
  added the media type application/msword for the response with the status
- info
  added the media type application/rtf for the response with the status
- info
  added the media type application/vnd.ms-excel for the response with the status
- info
  added the media type application/vnd.ms-excel.sheet.binary.macroenabled.12 for the response with the status
- info
  added the media type application/vnd.oasis.opendocument.presentation-template for the response with the status
- info
  added the media type application/vnd.oasis.opendocument.spreadsheet-template for the response with the status
- info
  added the media type application/vnd.oasis.opendocument.text-template for the response with the status
- info
  added the media type application/xhtml+xml for the response with the status
- info
  added the media type application/zip for the response with the status
- info
  added the media type image/webp for the response with the status
- info
  added the media type image/x-portable-bitmap for the response with the status
- info
  added the media type image/x-portable-graymap for the response with the status
- info
  added the media type image/x-portable-pixmap for the response with the status
- info
  added the media type image/x-wmf for the response with the status
- info
  added the media type text/markdown for the response with the status
- info
  added the non-success response with the status

Operation history