--- title: "Convert a document" method: POST path: "/render/template" tags: ["Convert"] --- # Convert a document `POST /render/template` ## Request - Base URL: `https://api.carbone.io` - URL: `https://api.carbone.io/render/template` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Convert your documents to 100+ formats, including PDF, ODT, DOCX, JPG, PNG, Markdown, CSV, ODS, XLSX, CSV, ODP, PPTX, XML, HTML, TXT, IDML, and many more. See the [full conversion matrix](https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type) for all supported input/output format combinations. **Two workflows are available for document conversion**: 1. **Inline (base64)**: Send the document as a base64-encoded string in the request body field named "template". Use the special endpoint `POST /render/template?download=true`. No prior upload is needed. 2. **Pre-uploaded template**: Upload the document once with `POST /template`, then convert it on demand using its `templateId` or `versionId` via `POST /render/{templateId-or-versionId}?download=true`. **Converters**: set the `converter` field 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 below and the [converters documentation](https://carbone.io/documentation/developer/http-api/generate-reports.html#converters). **Notes**: - Set the `download` query parameter to `true` to receive the converted file as a direct stream, or `false` (default) to receive a `renderId` for a separate `GET /render/{renderId}` download call. - For large files, set the `carbone-webhook-url` header: Carbone processes the conversion in the background and POSTs the result to your server when done. ## Query parameters - `download` boolean ## Headers - `carbone-version` '5' | '4' | '3' | 'staging', required - `carbone-webhook-url` string - `carbone-webhook-header-authorization` string - `carbone-egress-header-authorization` string ## Request body - ConvertInlineRequestBody - `template` string, required: **Required for inline conversion.** The source document encoded as a base64 string. Supported input formats: DOCX, XLSX, PPTX, PDF, ODT, ODS, ODP, ODG, TXT, CSV, HTML, XHTML, SVG, MD (Markdown), IDML, XML. - `data` union: Optional (from `carbone-version: 5`). JSON data-set merged into the document using `{d.}` tags. Omit `data` for a pure conversion: Carbone skips templating and leaves tags unchanged. Pass `{}` to run templating with an empty data-set (tags resolve to empty). - object - unknown[] - unknown - `convertTo` union: Output format for the converted/generated document. Can be a simple string (format name) or an object with advanced options (PDF password, watermark, image quality, CSV separator, etc.). **Simple string examples:** `"pdf"`, `"docx"`, `"xlsx"`, `"pptx"`, `"odt"`, `"ods"`, `"odp"`, `"html"`, `"csv"`, `"txt"`, `"png"`, `"jpg"`, `"svg"`, `"epub"`, `"md"`, `"webp"` **Full conversion matrix:** https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type **Object form (PDF with options):** ```json { "formatName": "pdf", "formatOptions": { "EncryptFile": true, "DocumentOpenPassword": "s3cr3t", "Watermark": "CONFIDENTIAL" } } ``` **Object form (PDF with multiple watermarks):** ```json { "formatName": "pdf", "formatOptions": { "Watermarks": [ { "text": "Confidential - Page {#PAGE_NUMBER} / {#PAGE_TOTAL}", "anchor": "center", "rotation": -45, "opacity": 0.1 } ] } } ``` **Object form (JPG with options):** ```json { "formatName": "jpg", "formatOptions": { "Quality": 80, "ColorMode": 0 } } ``` **Object form (image with Chromium):** `converter` must be `"C"`. ```json { "formatName": "webp", "formatOptions": { "PixelWidth": 1200, "Scale": 2, "Quality": 80 } } ``` **Object form (CSV with options):** ```json { "formatName": "csv", "formatOptions": { "fieldSeparator": ";", "textDelimiter": "\"", "characterSet": "76" } } ``` - string: Target format name (e.g. pdf, docx, xlsx, pptx, odt, ods, html, csv, png, jpg, svg, epub, md, webp…) - object: Target format with advanced options. - `formatName` string, required: Target format name. - `formatOptions` object: Format-specific options. See the full option list for each format: - PDF: https://carbone.io/documentation/developer/http-api/generate-reports.html#pdf-options - Images: https://carbone.io/documentation/developer/http-api/generate-reports.html#image-options - CSV: https://carbone.io/documentation/developer/http-api/generate-reports.html#csv-options - Watermarks: https://carbone.io/documentation/developer/http-api/generate-reports.html#watermark-options PDF options availability varies by converter: LibreOffice (`L`) supports all of them, Carbone ICE (`I`), Chromium (`C`) and OnlyOffice (`O`) only the Security and Watermark options. Image options apply to `jpg`, `jpeg`, `png` and `webp`. - `SelectPdfVersion` 0 | 1 | 2 | 3 | 4 | 15 | 16 | 17 | 20: PDF version to emit. 0: PDF 1.6 Standard. 1: PDF/A-1 (ISO 19005-1:2005). 2: PDF/A-2 (ISO 19005-2:2011). 3: PDF/A-3 (ISO 19005-3:2012). 4: PDF/A-4 (ISO 19005-4). 15: PDF 1.5 Standard. 16: PDF 1.6 Standard. 17: PDF 1.7 Standard. 20: PDF 2.0 Standard. LibreOffice only. - `ConvertOOoTargetToPDFTarget` boolean: Renames .od[tpgs] links to .pdf in the exported PDF, leaving the source untouched. LibreOffice only. - `ExportFormFields` boolean: Specifies whether form fields are exported as widgets or only as fixed print representation. LibreOffice only. - `ExportLinksRelativeFsys` boolean: Exports file system hyperlinks as relative to the source document. LibreOffice only. - `ExportNotes` boolean: Specifies if notes are exported to PDF. LibreOffice only. - `ExportNotesPages` boolean: Specifies if notes pages are exported to PDF (Impress only). LibreOffice only. - `FormsType` 0 | 1 | 2 | 3: Format for PDF form submission. 0: FDF. 1: PDF. 2: HTML. 3: XML. LibreOffice only. - `IsAddStream` boolean: Adds a stream containing the original document for archiving (PDF Import only). LibreOffice only. - `IsSkipEmptyPages` boolean: Suppresses auto-inserted empty pages (Writer only). LibreOffice only. - `UseTransitionEffects` boolean: Exports slide transitions to PDF (Impress only). LibreOffice only. - `DocumentOpenPassword` string: Password required to open the PDF. Only active when `EncryptFile` is true. - `EncryptFile` boolean: Encrypt the PDF with AES-256; the `DocumentOpenPassword` is required to open it. The document properties (Title, Author, Subject, and the other Info strings) are encrypted as well, so they cannot be read without the password. - `PermissionPassword` string: Password required to change restricted permissions. Only active when `RestrictPermissions` is true. - `RestrictPermissions` boolean: Enables restricted permissions in the PDF document (printing, copying, changes). Must be used with `PermissionPassword`. - `Changes` 0 | 1 | 2 | 3 | 4: What changes are allowed in the PDF. 0: None. 1: Insert/delete/rotate pages. 2: Fill forms. 3: Comment/fill forms. 4: Any except page extraction. Requires `RestrictPermissions: true` and `PermissionPassword`. - `EnableCopyingOfContent` boolean: Allows copying content to other documents. Requires `RestrictPermissions: true` and `PermissionPassword`. - `EnableTextAccessForAccessibilityTools` boolean: Allows text extraction for accessibility tools. Requires `RestrictPermissions: true` and `PermissionPassword`. - `Printing` 0 | 1 | 2: Allowed printing. 0: None. 1: Low resolution (150 DPI). 2: Max resolution. Requires `RestrictPermissions: true` and `PermissionPassword`. - `MaxImageResolution` 75 | 150 | 300 | 600 | 1200: Reduce images to this DPI when `ReduceImageResolution` is true. LibreOffice only. - `ReduceImageResolution` boolean: Reduces image resolution to `MaxImageResolution`. LibreOffice only. - `UseLosslessCompression` boolean: Use PNG (lossless) or JPEG compression for graphics. LibreOffice only. - `Watermark` string: Legacy field (backward compatible). Renders a single centered watermark at 45° with default styling on every page of the exported PDF file. It counts towards the maximum of 4 watermarks. Supported by all converters. - `Watermarks` object[]: New in v5.3.0. Define up to 4 watermarks per document, each fully configurable. Can be used simultaneously with the legacy `Watermark` field, which counts towards the 4: above that, the render returns `A maximum of 4 watermarks can be used at the same time`. Supported by all converters. - `text` string, required: The watermark label. Supports `{#PAGE_NUMBER}` and `{#PAGE_TOTAL}` variables for dynamic page numbering. - `anchor` 'topLeft' | 'top' | 'topRight' | 'left' | 'center' | 'right' | 'bottomLeft' | 'bottom' | 'bottomRight': Position of the watermark on the page. - `offsetX` number: Horizontal offset in points (pt) from the anchor. In PDFs, the origin is bottom-left, so positive values move right. - `offsetY` number: Vertical offset in points (pt) from the anchor. Positive values move up. - `rotation` number: Rotation in degrees, between -360 and 360. Defaults to 45 for the `center` anchor, 0 for others. For non-center anchors, only 0, 90, or -90 are allowed. - `color` string: Watermark text color in `#RGB` or `#RRGGBB` format. - `size` number: Font size in pt. For `center` anchor, defaults to automatic. For all other anchors, defaults to 12. - `opacity` number: Opacity between 0 and 1. For `center` anchor, defaults to 0.1. For all other anchors, defaults to 1. - `font` 'Courier' | 'Courier-Bold' | 'Courier-Oblique' | 'Courier-BoldOblique' | 'Helvetica' | 'Helvetica-Bold' | 'Helvetica-Oblique' | 'Helvetica-BoldOblique' | 'Times-Roman' | 'Times-Bold' | 'Times-Italic' | 'Times-BoldItalic': Font family for the watermark text. - `fromPage` integer: First page (1-based) on which the watermark is applied. - `toPage` integer: Last page (1-based) on which the watermark is applied. Defaults to all remaining pages. - `UseTaggedPDF` boolean: Creates a PDF with special tags (Tagged PDF). LibreOffice only. - `PDFUACompliance` boolean: Enables the PDF/UA Universal Accessibility standard (ISO 14289). LibreOffice only. - `AllowDuplicateFieldNames` boolean: Allows export of multiple form fields with the same name. LibreOffice only. - `CenterWindow` boolean: Opens the PDF centered on screen. LibreOffice only. - `DisplayPDFDocumentTitle` boolean: Shows the document title in the viewer window. LibreOffice only. - `ExportBookmarks` boolean: Exports bookmarks to PDF. LibreOffice only. - `ExportBookmarksToPDFDestination` boolean: Exports bookmarks as named destinations. LibreOffice only. - `FirstPageOnLeft` boolean: Used with `PageLayout`: the odd first page appears on the left. LibreOffice only. - `HideViewerMenubar` boolean: Hides the PDF viewer menubar. LibreOffice only. - `HideViewerToolbar` boolean: Hides the PDF viewer toolbar. LibreOffice only. - `HideViewerWindowControls` boolean: Hides the PDF viewer window controls. LibreOffice only. - `InitialPage` integer: Page number on which the PDF opens. LibreOffice only. - `InitialView` 0 | 1 | 2: Display mode on open. 0: None. 1: Outline pane. 2: Thumbnail pane. LibreOffice only. - `Magnification` 0 | 1 | 2 | 3 | 4: Open action. 0: Default. 1: Fit page. 2: Fit width. 3: Fit width of bounding box. 4: Zoom set by `Zoom`. LibreOffice only. - `OpenBookmarkLevels` integer: Number of bookmark levels opened on startup (-1 = all). LibreOffice only. - `OpenInFullScreenMode` boolean: Opens the PDF in full screen. LibreOffice only. - `PageLayout` 0 | 1 | 2 | 3: Page layout. 0: Reader default. 1: Single. 2: One column. 3: Two columns (see `FirstPageOnLeft`). LibreOffice only. - `PageRange` string: Range of pages to include (e.g. '1-5'). Leave unset to export all pages. LibreOffice only. - `PDFViewSelection` 0 | 1 | 2: PDF viewing. 0: All links as URI. 1: PDF reader only (not for PDF/A-1). 2: Internet browser with plugin (see `ExportBookmarksToPDFDestination`). LibreOffice only. - `ResizeWindowToInitialPage` boolean: Resizes the viewer to the first page at open. LibreOffice only. - `Zoom` integer: Zoom percent when `Magnification` is 4. LibreOffice only. - `PixelWidth` integer: Output image width in pixels. LibreOffice: defaults to the document width. Chromium: also the layout width of the HTML document, defaults to the document width with a minimum of 800 px (media queries and `vw` units use the 800 px window), integer from 1 to 16383. - `PixelHeight` integer: Output image height in pixels. LibreOffice: defaults to the document height. Chromium: applies only when `FullPage` is false, defaults to 600, integer from 1 to 16383. - `FullPage` boolean: Captures the whole height of the document. When false, the image is `PixelWidth` x `PixelHeight`. Chromium only. - `Scale` number: Pixel density. 2 doubles the width and the height of the image: text and SVG stay sharp, embedded bitmap images can be blurry. Chromium only. - `ColorMode` number: Color mode. 0: Colors. 1: Greyscale. LibreOffice only. - `Quality` number: JPG/JPEG and WebP quality: low values mean high compression and small files, 100 means the highest quality. LibreOffice: 1 to 100, defaults to 100 for images; for a `pdf` export, it sets the JPG compression quality of images and defaults to 90. Chromium: 0 to 100, defaults to 90, and 100 produces a lossless WebP. - `Compression` number: PNG compression level, from 0 (disabled) to 9 (maximum). LibreOffice only. - `Interlaced` number: PNG interlacing. 0: Not interlaced. 1: Interlaced. LibreOffice only. - `Translucent` number: PNG transparency. 0: No transparent background. 1: Transparent background. LibreOffice only. - `fieldSeparator` string: CSV field separator character (e.g. `,`, `;`, `+`). - `textDelimiter` string: CSV text delimiter character (e.g. `"`). - `characterSet` string: CSV character encoding. See https://wiki.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options for accepted values (e.g. '76' for UTF-8). - `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. - `timezone` string: Convert document dates to a timezone. The date must be chained with the `:formatD` formatter. List of accepted timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones - `lang` string: Locale of the generated document, used for translations `{t()}`, number formatting `:formatN`, and currencies `:formatC`. List of supported locales: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js - `complement` object: Extra data accessible in the template with `{c.}` instead of `{d.}`. - `variableStr` string: Predefined alias. See: https://carbone.io/documentation/design/substitutions/aliases.html#alias - `reportName` string: Static or dynamic output file name returned in the `content-disposition` header. The output extension is appended automatically, so do not include it. Supports multiple Carbone tags, e.g. `{d.type}-{d.date}`. - `enum` object: List of enumerations for use with the `convEnum` formatter. See: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html#convenum-type - `translations` object: Localization dictionary used with `{t( )}` tags. Requires the `lang` option. - `currencySource` string: Source currency from your JSON data, used by `formatC` for currency conversion. - `currencyTarget` string: Target currency for the generated document, used by `formatC`. - `currencyRates` object: Currency exchange rates for `formatC` conversion. - `hardRefresh` boolean: If true, recomputes pagination and table of contents at the end of rendering. 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. - `batchSplitBy` string: 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`. - `batchReportName` string: 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. - `preReleaseFeatureIn` integer: 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. Learn more: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features - `failOn` string[]: Optional (v5.15.0+). Array of conditions that stop the render and return an error. `IMAGE_URL_ERROR`: an image that cannot be downloaded from its URL stops the report. 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 ## Response `200` 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. - object - `success` boolean - `data` object: In asynchronous mode (`carbone-webhook-url` header set), `renderId` is an empty string: the real one is sent to the webhook. - `renderId` string - `message` string: 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. ## Other responses - `400`: The request could not be accepted: wrong content type, or document that cannot be read. - `401`: Unauthorized, please provide a correct API key on the `Authorization` header. The API key is available on your Carbone account: https://account.carbone.io. - `404`: The template is not found - `413`: The JSON body or the base64 document exceeds the size limit. - `415`: Template format not supported, it must be an XML-based or Text-based document. - `422`: The 'data' property is missing on the body request. This error applies to `carbone-version: 4` only: from `carbone-version: 5`, `data` is optional and omitting it converts the file without templating (tags left unchanged). - `499`: Client Closed Request: the client closed the connection before the end of the document generation, and Carbone stopped the generation. The client is already disconnected, so this status mainly shows in logs and metrics. - `500`: Something went wrong when merging the JSON data-set into the template (the design of the template has an issue), or when setting up the webhook. ## Changes - **2026-11-06** `c06cc573e3b0`: 10 breaking, 2 warning, 75 info - the `carbone-version` request header's property undefined was restricted to a list of enum values - the `header` request parameter `carbone-version` was restricted to a list of enum values - for the `query` request parameter `download`, default value was changed from `true` to `false` - request property `batchOutput` was restricted to a list of enum values - …83 more - **2026-06-13** `fb25492a25ce`: 1 info - endpoint added [Operation history](https://skmtc.dev/carbone/apis/carbone-api/changes/render/template/post.md) --- [API](https://skmtc.dev/carbone/apis/carbone-api.md) - [All operations](https://skmtc.dev/carbone/apis/carbone-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carbone/apis/carbone-api/revisions/c06cc573e3b0?raw)