Raw schema
{
"type": "object",
"properties": {
"templateId": {
"description": "The ID of a previously uploaded template to render. Two ID formats are accepted: (1) Template ID (64-bit) — stable identifier shared across versions; Carbone automatically uses the deployed version. (2) Version ID (SHA-256) — pins rendering to a specific version regardless of deployment status. Both are returned by upload_template. Mutually exclusive with template — provide exactly one, never both.",
"type": "string",
"minLength": 1
},
"template": {
"description": "Inline template for one-shot render without storing a template first. Two input forms are accepted: (1) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (2) Base64-encoded string — the raw file content encoded as base64. Local file paths are NOT accepted — this server is reached over HTTP, so a path would resolve on the server's disk rather than yours and is rejected. Upload the bytes as base64, or host the file at a URL. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both.",
"type": "string",
"minLength": 1
},
"data": {
"description": "JSON data merged into the template — an object, or a top-level array (accessed with {d[i].field}). Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == \"active\" ? \"Yes\" : \"No\"}. Optional — if omitted, defaults to an empty object {} so the template is simply converted (tags resolve to empty). Useful to convert a stored template by templateId without data injection. Instead of inlining a large dataset, you may pass a STRING reference to the JSON: an HTTPS URL or a base64-encoded JSON string (local file paths are not accepted over HTTP) — it is read and parsed server-side.",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "string"
}
]
},
"convertTo": {
"description": "Output format. If omitted, the output matches the template format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\". Web/text : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive : \"zip\" (use with batchSplitBy for batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { ... } } for PDF-specific options.",
"anyOf": [
{
"type": "string",
"enum": [
"pdf",
"docx",
"doc",
"xlsx",
"xls",
"pptx",
"ppt",
"odt",
"ods",
"odp",
"odg",
"html",
"xhtml",
"txt",
"csv",
"md",
"xml",
"rtf",
"png",
"jpg",
"jpeg",
"webp",
"svg",
"tiff",
"bmp",
"gif",
"zip",
"idml",
"epub",
"cdr"
]
},
{
"type": "object",
"properties": {
"formatName": {
"type": "string",
"enum": [
"pdf",
"docx",
"doc",
"xlsx",
"xls",
"pptx",
"ppt",
"odt",
"ods",
"odp",
"odg",
"html",
"xhtml",
"txt",
"csv",
"md",
"xml",
"rtf",
"png",
"jpg",
"jpeg",
"webp",
"svg",
"tiff",
"bmp",
"gif",
"zip",
"idml",
"epub",
"cdr"
],
"description": "Target format name."
},
"formatOptions": {
"description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } compression quality 0-100; Images — { \"density\": 150 } DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"formatName"
]
}
]
},
"converter": {
"description": "Converter engine. Only relevant when convertTo is \"pdf\" (or an image rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML/CSS/JS templates — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default.",
"type": "string",
"enum": [
"L",
"C",
"O",
"I"
]
},
"timezone": {
"description": "IANA timezone used to convert dates in the rendered document. Default: \"Europe/Paris\". Applied when templates use the :formatD formatter, e.g. {d.date:formatD(YYYY-MM-DD HH:mm)}. Common values: \"UTC\", \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\", \"Europe/Paris\", \"Europe/Berlin\", \"Asia/Tokyo\", \"Asia/Shanghai\", \"Australia/Sydney\". Full list (TZ identifier column): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones",
"type": "string"
},
"lang": {
"description": "Locale of the generated document. Affects three things: (1) {t(key)} translation tags — selects the matching translation from the translations map. (2) :formatN number formatter — applies locale-specific thousand/decimal separators. (3) :formatC currency formatter — applies locale-specific currency symbols and formatting. Format: BCP-47 lowercase, e.g. \"fr-fr\", \"en-us\", \"de-de\", \"es-es\", \"pt-br\", \"zh-cn\", \"ja-jp\". Full list: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js",
"type": "string"
},
"complement": {
"description": "Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { \"company\": \"Acme Corp\", \"address\": \"123 Main St\", \"vatNumber\": \"FR12345\" }. Like data, may instead be passed by reference as a string — an HTTPS URL or a base64-encoded JSON string (local file paths are not accepted over HTTP).",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "string"
}
]
},
"variableStr": {
"description": "Carbone alias expressions evaluated once before rendering, available everywhere in the template. Used to pre-compute reusable values or shorten repetitive paths. Syntax: \"{#aliasName = expression}\". Example: \"{#fullName = d.firstName + \\\" \\\" + d.lastName}{#total = d.price * d.qty}\". Aliases are then used in the template as {#fullName}, {#total}. Documentation: https://carbone.io/documentation.html#alias",
"type": "string"
},
"reportName": {
"description": "Filename (WITHOUT extension) for the generated document, returned in the Content-Disposition header. Carbone automatically appends the extension that matches convertTo, so do not include one — passing \"invoice.pdf\" yields \"invoice.pdf.pdf\". Supports Carbone tags resolved against the data at render time. Examples: \"invoice\" (static), \"{d.type}-{d.id}\" (dynamic), \"{d.client}-{d.date:formatD(YYYY-MM)}\".",
"type": "string"
},
"enum": {
"description": "Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { \"STATUS\": { \"1\": \"Active\", \"2\": \"Inactive\", \"3\": \"Pending\" }, \"ROLE\": { \"A\": \"Admin\", \"U\": \"User\" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. May instead be passed by reference as a string — an HTTPS URL or a base64-encoded JSON string (local file paths are not accepted over HTTP). Documentation: https://carbone.io/documentation.html#convenum-type-",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
{
"type": "string"
}
]
},
"translations": {
"description": "Translation map for multilingual documents. Requires \"lang\" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { \"fr-fr\": { \"greeting\": \"Bonjour\", \"total\": \"Total\" }, \"en-us\": { \"greeting\": \"Hello\", \"total\": \"Total\" } }. These dictionaries get large, so you may instead pass a string reference — an HTTPS URL or a base64-encoded JSON string (local file paths are not accepted over HTTP). Documentation: https://carbone.io/documentation.html#translations",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
{
"type": "string"
}
]
},
"currencySource": {
"description": "ISO 4217 currency code of the monetary amounts in the JSON data. Used by the :formatC formatter as the conversion source. Must be set together with currencyTarget and currencyRates. Example: \"EUR\" if all prices in your data are in euros.",
"type": "string"
},
"currencyTarget": {
"description": "ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: \"USD\" to display prices in US dollars. Documentation: https://carbone.io/documentation.html#formatc-precisionorformat-",
"type": "string"
},
"currencyRates": {
"description": "Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { \"EUR\": 1, \"USD\": 1.08, \"GBP\": 0.86, \"JPY\": 160.5 }. May instead be passed by reference as a string — an HTTPS URL or a base64-encoded JSON string (local file paths are not accepted over HTTP).",
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
{
"type": "string"
}
]
},
"keepTags": {
"description": "If true, SKIP templating entirely and leave every Carbone tag in the document exactly as written — {d.customer} comes out as the literal text \"{d.customer}\", formatters included. Use it to proof a stored template in another format (e.g. render templateId to PDF to check the tag layout), or to convert a template between formats while it stays a template. Mutually exclusive with data — passing both is rejected, because data would have nothing to fill. Note the difference from omitting data: no data renders the template with an EMPTY dataset, so every tag resolves to an empty string; keepTags leaves the tags themselves in place. Requires Carbone 5.9.0+ (carbone-version: 5).",
"type": "boolean"
},
"hardRefresh": {
"description": "If true, Carbone recomputes pagination and refreshes the table of contents after rendering. Requires convertTo to be defined. Use this for DOCX/ODT templates that contain a TOC field or cross-references that need updating after data injection.",
"type": "boolean"
},
"batchSplitBy": {
"description": "JSON path to the array in your data that drives batch generation. One document is generated per element of the array. Two forms: \"d\" when data itself IS the array (one report per top-level element), or \"d.arrayName\" to split on a child array. Example: \"d.invoices\" — produces one PDF per item in data.invoices. Example: \"d.employees\" — produces one contract per employee. Carbone Cloud allows 1 to 100 objects per batch (on-premise follows the nbReportMaxPerBatch setting). Batch is ALWAYS asynchronous — webhookUrl is required. Pair with batchOutput to choose ZIP or a single concatenated PDF, and batchReportName to name each document.",
"type": "string"
},
"batchOutput": {
"description": "How the batch result is packaged. Defaults to \"zip\". \"zip\" — every generated document is bundled into a single ZIP archive (use batchReportName to name each entry). \"pdf\" — all documents are CONCATENATED into one continuous PDF instead of being zipped; this requires convertTo to be \"pdf\" as well. Must be used together with batchSplitBy.",
"type": "string",
"enum": [
"zip",
"pdf"
]
},
"batchReportName": {
"description": "Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: \"invoice-{d.id}.pdf\", \"{d.client.name}-{d.date}.docx\". Carbone sanitises the result — path separators, \"..\", Windows-forbidden and control characters each become an underscore — and appends an index to duplicates (\"report_1.pdf\", \"report_2.pdf\"), so a pattern that resolves to the same name for several items will not silently drop documents. Only meaningful with batchOutput: \"zip\"; a concatenated \"pdf\" batch is a single file. Must be used together with batchSplitBy.",
"type": "string"
},
"webhookUrl": {
"description": "Webhook URL to enable asynchronous rendering. When provided, Carbone returns immediately and POSTs { \"success\": true, \"data\": { \"renderId\": \"...\" } } to this URL when the document is ready. The default render timeout is extended to 5 minutes on Carbone Cloud (vs 60 s for synchronous requests). Download the document with GET /render/:renderId once the webhook is received. Required when using batchSplitBy (batch generation is always asynchronous). Example: \"https://your-server.com/carbone-webhook\".",
"type": "string",
"format": "uri"
},
"webhookHeaders": {
"description": "Custom headers Carbone will include when POSTing to your webhookUrl. Pass plain header names as keys — the prefix \"carbone-webhook-header-\" is added automatically before sending to Carbone, and Carbone forwards the original header names to your webhook endpoint. Example: { \"authorization\": \"my-secret\", \"custom-id\": \"12345\", \"custom-name\": \"Jane Doe\" } — Carbone will call your URL with headers: authorization: my-secret, custom-id: 12345, custom-name: Jane Doe. Requires webhookUrl to be set.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"egressAuthorization": {
"description": "Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests while rendering — fetching external images ({d.imageUrl}), external PDFs (:appendFile / :attachFile), and calling webhooks. For example \"Bearer abc123\" or \"my-secret\" makes Carbone send `authorization: <value>` to those hosts. Only the authorization header can be customised; max 512 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value.",
"type": "string",
"maxLength": 512
},
"outputPath": {
"description": "NOT AVAILABLE on this server, which is reached over HTTP: the generated document would be written to the server's disk instead of yours, so passing outputPath is rejected. Use asAttachment to receive the bytes, or returnLink for a one-time download URL. Ignored for async/webhook renders (no document is returned inline).",
"type": "string"
},
"asAttachment": {
"description": "If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.",
"type": "boolean"
},
"returnLink": {
"description": "If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath, asAttachment, and webhookUrl (async).",
"type": "boolean"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
