Generate Document
render_documentRead-onlyIdempotent
Generate a document by merging a Carbone template with JSON data. Two modes: (1) pass templateId to use a previously uploaded template; (2) pass template (an HTTPS URL or a base64-encoded string (local file paths are not accepted over HTTP)) to upload and render in a single request without storing a template. Supports output format conversion, multilingual rendering, currency conversion, batch generation, and advanced PDF options (watermark, password, PDF/A). Without data, every tag resolves to empty; to keep the tags as written, pass keepTags: true (e.g. to proof a stored template), or use convert_document for a file. Async mode: pass webhookUrl. This tool then returns only Carbone's acceptance message, never the document: Carbone POSTs { "success": true, "data": { "renderId": "..." } } to the webhook, whose server downloads the document itself from GET /render/{renderId} (one-time, no auth). You cannot fetch it from here. Batch generation (batchSplitBy) is always delivered this way.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | 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]}. Conditions: {d.status:ifEQ(active):show(Yes):elseShow(No)}. Optional: if omitted, {} is sent, so every tag resolves to empty ("Hello {d.name}!" becomes "Hello !"). To keep the tags as written instead, pass keepTags: true (and no data). 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. | |
| enum | No | 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/design/advanced-features/key-value-mapping.html#convenum-type | |
| lang | No | 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 | |
| failOn | No | Conditions that stop the render and return an error (Carbone v5.15.0+). "IMAGE_URL_ERROR": an image that cannot be downloaded from its URL fails the render, instead of being replaced with the broken-image placeholder. Empty image values are skipped; base64 images, barcodes and charts are not concerned. Example: ["IMAGE_URL_ERROR"]. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#fail-on | |
| keepTags | No | 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. Not the same as 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. | |
| template | No | 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 input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first. Mutually exclusive with templateId — provide exactly one, never both. | |
| timezone | No | 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 | |
| convertTo | No | Output format. If omitted, the output keeps the template format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. "doc", "xls" and "ppt" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: "pdf". With options: { "formatName": "pdf", "formatOptions": { ... } }. | |
| converter | No | Converter engine, used whenever the format changes (not only for PDF). If omitted, "L" is used. "L" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. "I" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over "O" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default "L" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). "O" OnlyOffice: DOCX, XLSX, PPTX to PDF. "C" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: "L" supports all of them; "O", "C" and "I" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters | |
| complement | No | 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). | |
| outputPath | No | 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). | |
| reportName | No | 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)}". With keepTags (no templating pass), this server names the file "<reportName>.<ext>" itself, literally (tags are not resolved). | |
| returnLink | No | 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 and asAttachment. Ignored when webhookUrl is set (no link is returned). | |
| templateId | No | 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. | |
| webhookUrl | No | Webhook URL that enables asynchronous rendering (render timeout raised to 5 minutes). This tool then returns only Carbone's acceptance message, never the document. When the document is ready, Carbone POSTs { "success": true, "data": { "renderId": "..." } } to this URL; the server behind it must download the document itself with GET /render/{renderId} on the Carbone API (one-time, no auth). You cannot fetch it from here. Required for batchSplitBy: batch output is always delivered this way. outputPath, asAttachment and returnLink are ignored in this mode. Example: "https://your-server.com/carbone-webhook". | |
| batchOutput | No | Batch result type, with batchSplitBy. "zip" (default): an archive of all generated documents. "pdf": the generated PDFs concatenated into one file; requires convertTo "pdf". | |
| hardRefresh | No | 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. | |
| variableStr | No | Carbone alias definitions applied to the whole template, as if written in it. An alias is a shortcut to a data path, not a variable: it stores no value and computes nothing (no arithmetic, no concatenation). Define with {#alias = d.path}, optionally with $parameters: {#mealOf($weekday) = d[weekday = $weekday]}. Use them in the template with {$alias}, e.g. {$mealOf(2).name}. Example: "{#buyer = d.order.customer}", then {$buyer.name} in the template renders d.order.customer.name. To store a computed value, use the :set formatter instead. Documentation: https://carbone.io/documentation/design/substitutions/aliases.html#alias | |
| asAttachment | No | 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 returned as an attachment. Ignored when outputPath or returnLink is set. | |
| batchSplitBy | No | Batch generation: one document per object of an array. Use "d" when data itself is an array, or "d.items" for a direct child array of data. Requires webhookUrl (batch is always asynchronous: the result goes to the webhook, not to this tool). At most 100 objects on Carbone Cloud. Combine with batchOutput and batchReportName. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#batch-processing | |
| translations | No | 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/design/advanced-features/translations-i18n.html | |
| currencyRates | No | 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). | |
| currencySource | No | 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. | |
| currencyTarget | No | 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/design/formatters/currency.html#formatc-precisionorformat-targetcurrency | |
| webhookHeaders | No | 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. | |
| batchReportName | No | Name of each file inside the batch ZIP, WITHOUT extension (Carbone appends it). Carbone tags are resolved against each batch item, e.g. "invoice-{d.id}". Ignored when batchOutput is "pdf". From v5.14, an index is appended to every file as soon as two names collide (invoice_1.pdf, invoice_2.pdf). Requires batchSplitBy. | |
| egressAuthorization | No | 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 511 characters. For webhook calls specifically, webhookHeaders.authorization (if set) overrides this value. | |
| preReleaseFeatureIn | No | Pre-release feature level for this render only: features and fixes introduced up to this tag apply, later ones stay disabled. Overrides the server default; a tag set in the template overrides it. Example: 5000000. Docs: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features |