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:

See the full conversion matrix for all supported input/output format combinations.

Convert a Document

/render/template?download=true

There are two ways to send the source file:

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: replace base64 -i webpage.html with base64 -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: replace base64 -i webpage.html with base64 -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: replace base64 -i drawing.svg with base64 -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: replace base64 -i document.docx with base64 -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: replace base64 -i presentation.pptx with base64 -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: replace base64 -i presentation.pptx with base64 -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: replace base64 -i spreadsheet.xlsx with base64 -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: replace base64 -i spreadsheet.xlsx with base64 -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: replace base64 -i document.md with base64 -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: replace base64 -i document.md with base64 -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: replace base64 -i document.docx with base64 -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: replace base64 -i document.pdf with base64 -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: replace base64 -i document.pdf with base64 -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: replace base64 -i document.pdf with base64 -w 0 document.pdf