HTTP API
Convert Documents
HTTP API to convert documents between 100+ formats in a single API call
Overview
Carbone converts documents between formats: send a file, get back a converted file.
Supported conversions include:
- Office to PDF - Convert DOCX, XLSX, PPTX, ODT, ODS, ODP, and ODG files to PDF.
- HTML to PDF - Convert raw HTML pages or web-based content to pixel-perfect PDF.
- HTML to Images - Convert raw HTML or XHTML pages, or web-based content, to PNG, JPG, or WEBP.
- SVG to PDF - Convert an SVG to a one-page PDF, or to PNG, JPG, or WEBP.
- PDF to Office - Convert PDF to DOCX, ODT, HTML, TXT (plain text extraction).
- PDF to Image - Convert PDF to PNG, JPG, or WEBP.
- Office to Office - DOCX ↔ ODT, XLSX ↔ CSV ↔ ODS, PPTX ↔ ODP.
- Office to Image - Convert DOCX / PPTX / XLSX to PNG, JPG, TIFF, SVG, WEBP.
- Office to MD - Convert DOCX/ODT to Markdown.
- MD to PDF, Office, or Images - Convert Markdown documents to PDF, DOCX, ODT, PNG or JPG.
- PDF processing - Apply password protection, watermarks, compliance settings, and more to any existing PDF.
See the full conversion matrix for all supported input/output format combinations.
Convert a Document
There are two ways to send the source file:
- For one-off conversions: pass the file as a base64-encoded string directly in the request body using
POST /render/template. The file is never stored. - For high-volume or repeated conversions of the same source file: upload it once with
POST /templateand reference it by ID withPOST /render/{templateId-or-versionId}whenever you need a new conversion. Learn more to generate a Document from a Template ID
Request headers
{
// REQUIRED
"authorization": "Bearer API_TOKEN",
"content-type": "application/json",
"carbone-version": "5",
// OPTIONAL Webhook for asynchronous rendering: For large files, use the webhook mode. Carbone processes the conversion in the background and POSTs the result to your server when done.
"carbone-webhook-url" : "https://your-url",
// OPTIONAL Webhook custom headers, where X is any header name. Ex: carbone-webhook-header-authorization. See asynchronous jobs: /documentation/developer/http-api/generate-reports.html#asynchronous-jobs
"carbone-webhook-header-X" : "headers value",
// OPTIONAL (v5.9.0+) Custom authorization header for egress traffic, shorter than 512 chars. See /documentation/developer/http-api/generate-reports.html#egress-authentication
"carbone-egress-header-authorization" : "my-secret"
}
Request body
{
// REQUIRED - base64-encoded source document.
// Supported input formats: DOCX, XLSX, PPTX, PDF, ODT, ODS, ODP, ODG, TXT, CSV, HTML, XHTML, SVG, MD, IDML, XML
"template": "BASE64_ENCODED_FILE_CONTENT",
// REQUIRED - target format. Simple string or an object for advanced options (password, watermark, image quality…)
"convertTo": "pdf",
// OPTIONAL - Converter engine, used whenever the output format differs from the input format (not only for "pdf").
// Accepted Values: "L" = LibreOffice (default): Best balance of speed and compatibility, converts to all formats of the conversion matrix | "O" = OnlyOffice: Office files to PDF. | "C" = Chromium: HTML to PDF, JPG, PNG, WEBP. | "I" = Carbone ICE: The fastest DOCX/ODT to PDF (v5.14.0+). See /documentation/developer/http-api/generate-reports.html#converters
"converter": "L",
// OPTIONAL - The filename in the `content-disposition` header defaults to `report.<ext>`.
// Override it with `reportName` field (the output extension is appended automatically).
"reportName": "invoice"
}
Note: The convertTo field accepts a simple string (e.g. "pdf", "docx") or an object for advanced options (password, watermark, image quality…). See the full conversion matrix for all supported input/output format combinations.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
download |
Boolean | No | true: returns the generated 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} (more info).false: returns a JSON object with a renderId; use GET /render/{renderId} to download the file in a second call (see Download Reports). |
Response
| Status Code | Body | |
|---|---|---|
| 200 | File stream (when download=true) or { "success": true, "data": { "renderId": "..." } } |
|
| 400 | { "success": false, "error": ""Content-Type" header is not "application/json"" } |
|
| 400 | { "success": false, "error": "Cannot retrieve template" } |
|
| 401 | { "success": false, "error": "Unauthorized, please provide a correct API key on the "Authorization" header. The API key is available on your Carbone account: https://account.carbone.io" } |
|
| 401 | { "success": false, "error": "Unauthorized Access: The API key or access token has expired." } |
|
| 413 | { "success": false, "error": "Content too large, the JSON size limit is X Bytes" } |
|
| 413 | { "success": false, "error": "Template too large, the file size limit is X Bytes" } |
|
| 415 | { "success": false, "error": "Template format not supported, it must be an XML-based or Text-based document: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML, TXT, MD, CSV, XML, SVG, etc..." } |
|
| 422 | { "success": false, "error": "Missing "data" property in body" }Note: From carbone-version: 5, data is optional: omitting it converts the file without templating (tags left unchanged). This error applies to carbone-version: 4 only. |
|
| 500 | { "success": false, "error": "Unable to generate the document. {cause}", "data": { "renderId": "" } }The message after Unable to generate the document. gives the cause, for example: Format "docx" can't be converted to "xlsx". |
|
| 500 | { "success": false, "error": "Error while setting up the webhook" } |
HTML to PDF
Convert HTML to PDF with the Chromium engine ("converter": "C"). The PDF matches what Chrome displays: modern CSS, web fonts, flexbox and grid layouts, print styles. Send the HTML page, get the PDF back, with no browser to install or scale on your side.
Chromium runs isolated on the Carbone servers: JavaScript is disabled and the page has no network access. Carbone downloads the images, stylesheets and fonts of the page itself and passes them to Chromium. Page size, margins, headers and footers are set in the HTML with the <carbone-pdf-options>, <carbone-pdf-header> and <carbone-pdf-footer> elements.
This is the usual way to turn HTML produced by an LLM, a web app or a no-code builder into a PDF.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i webpage.html)\",
\"convertTo\": \"pdf\",
\"converter\": \"C\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i webpage.htmlwithbase64 -w 0 webpage.html
HTML to Images
Render an HTML or XHTML page as a PNG, JPG or WebP image with the Chromium engine ("converter": "C"), for example for a social share card or a preview. The width, the height, the pixel density and the quality are set with formatOptions (see Image options).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i webpage.html)\",
\"convertTo\": { \"formatName\": \"png\", \"formatOptions\": { \"PixelWidth\": 1200, \"Scale\": 2 } },
\"converter\": \"C\"
}" \
--output result.png
💡 Linux users: replacebase64 -i webpage.htmlwithbase64 -w 0 webpage.html
SVG to PDF
Convert an SVG file to PDF with the Chromium engine ("converter": "C"). The PDF has a single page, sized like the SVG: its width and height attributes, or its viewBox. Useful for charts, diagrams and drawings produced by your app.
To get an image instead, set convertTo to png, jpg or webp. Use the Scale option for a larger, sharper image (see Image options).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i drawing.svg)\",
\"convertTo\": \"pdf\",
\"converter\": \"C\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i drawing.svgwithbase64 -w 0 drawing.svg
DOCX to PDF
Convert a Word document to PDF with LibreOffice ("converter": "L"), the default converter. For large documents, Carbone ICE ("converter": "I") is faster (see Converters). The same request works for ODT.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.docx)\",
\"convertTo\": \"pdf\",
\"converter\": \"L\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i document.docxwithbase64 -w 0 document.docx
PPTX to PDF
Convert a PowerPoint presentation to PDF. Every slide is preserved as a page. The same request works for ODP (LibreOffice Impress).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i presentation.pptx)\",
\"convertTo\": \"pdf\",
\"converter\": \"L\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i presentation.pptxwithbase64 -w 0 presentation.pptx
PPTX to PNG
Render the first slide of a presentation as a PNG image, for a thumbnail or a preview. The same request works for ODP. The dimensions and the color mode are set with formatOptions (see Image options).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i presentation.pptx)\",
\"convertTo\": \"png\"
}" \
--output slide.png
💡 Linux users: replacebase64 -i presentation.pptxwithbase64 -w 0 presentation.pptx
XLSX to PDF
Convert an Excel spreadsheet to PDF. The result is the spreadsheet as it prints. The same request works for ODS.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i spreadsheet.xlsx)\",
\"convertTo\": \"pdf\",
\"converter\": \"L\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i spreadsheet.xlsxwithbase64 -w 0 spreadsheet.xlsx
XLSX to CSV
Export a spreadsheet as CSV. By default, the separator is a comma and the encoding is UTF-8. The separator, the text delimiter and the encoding are set with formatOptions (see CSV options).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i spreadsheet.xlsx)\",
\"convertTo\": \"csv\"
}" \
--output result.csv
💡 Linux users: replacebase64 -i spreadsheet.xlsxwithbase64 -w 0 spreadsheet.xlsx
MD to PDF
Convert a Markdown file to PDF, for example the Markdown written by an LLM.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.md)\",
\"convertTo\": \"pdf\",
\"converter\": \"L\"
}" \
--output result.pdf
💡 Linux users: replacebase64 -i document.mdwithbase64 -w 0 document.md
MD to DOCX
Convert a Markdown file to a Word document.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.md)\",
\"convertTo\": \"docx\",
\"converter\": \"L\"
}" \
--output result.docx
💡 Linux users: replacebase64 -i document.mdwithbase64 -w 0 document.md
DOCX to MD
Convert a Word document to Markdown, for example to feed an LLM or a static site generator. The output format is md.
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.docx)\",
\"convertTo\": \"md\",
\"converter\": \"L\"
}" \
--output result.md
💡 Linux users: replacebase64 -i document.docxwithbase64 -w 0 document.docx
PDF to Image
Render a PDF as a PNG, JPG or WebP image, for a thumbnail or a preview. The dimensions and the quality are set with formatOptions (see Image options).
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.pdf)\",
\"convertTo\": \"png\"
}" \
--output page.png
💡 Linux users: replacebase64 -i document.pdfwithbase64 -w 0 document.pdf
PDF to PDF
Re-export a PDF to apply options: password, watermarks, PDF/A, page range, print permissions, PDF/UA tags, image compression. All options go in the same formatOptions object and can be combined in one call (see PDF options).
Password protection
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.pdf)\",
\"hardRefresh\": true,
\"convertTo\": {
\"formatName\": \"pdf\",
\"formatOptions\": {
\"EncryptFile\": true,
\"DocumentOpenPassword\": \"s3cr3t\"
}
},
\"converter\": \"L\"
}" \
--output protected.pdf
💡 Linux users: replacebase64 -i document.pdfwithbase64 -w 0 document.pdf
PDF/A-4 and PDF/UA (accessibility)
curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
--header 'carbone-version: 5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_TOKEN' \
--data-raw "{
\"template\": \"$(base64 -i document.pdf)\",
\"hardRefresh\": true,
\"convertTo\": {
\"formatName\": \"pdf\",
\"formatOptions\": {
\"SelectPdfVersion\": 4,
\"PDFUACompliance\": true,
\"UseTaggedPDF\": true
}
},
\"converter\": \"L\"
}" \
--output compliant.pdf
💡 Linux users: replacebase64 -i document.pdfwithbase64 -w 0 document.pdf