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.
PDF to Office — Convert PDF to DOCX, ODT, HTML, TXT (plain text extraction).
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

/render/template?download=true

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 /template and reference it by ID with POST /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" : "http://your-url",
}

Request body

{
  // REQUIRED — pass an empty object {} when not injecting data
  "data": {},

  // REQUIRED — base64-encoded source document. 
  // Supported input formats: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, ODT, ODS, ODP, ODG, RTF, TXT, CSV, HTML, XHTML, 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 — PDF converter engine, only relevant when "convertTo" is "pdf". 
  // Accepted Values: "L" = LibreOffice (default) Best balance of speed and compatibility |  "O" = OnlyOffice: Maximum fidelity for Office files. |  "C" = Chromium: Perfect for HTML to PDF.
  "converter": "L",

  // OPTIONAL — The filename in the `content-disposition` header defaults to `report.<ext>`.
  // Override it with `reportName` field: it supports Carbone tags for dynamic filenames `"reportName": "{d.company}-{d.date}.pdf"`
  "reportName": "invoice.pdf"
}

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 file directly as a stream. `false`: returns a `renderId` JSON object; use `GET /render/{renderId}` to download the file (see Downdload Reports).

Response

Status	Body
200	File stream (when `download=true`) or `{ "success": true, "data": { "renderId": "..." } }`
400	`{ "success": false, "error": "'Content-Type' header is not 'application/json'" }`
401	`{ "success": false, "error": "Unauthorized, please provide a valid API key" }`
422	`{ "success": false, "error": "Missing 'data' property in body" }`
500	`{ "success": false, "error": "Error while rendering template" }`

HTML to PDF

Carbone runs an optimised build of Chromium tuned for high-throughput server-side rendering, supporting modern CSS, JavaScript, and web fonts without any browser infrastructure to manage. The fastest path from HTML to PDF at scale. AI models, Web apps, Nocode App builders all produce HTML output and Carbone turns it into a PDF in one API call.

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 "{
    "data": {},
    "template": "$(base64 -i webpage.html)",
    "convertTo": "pdf",
    "converter": "C"
  }" \
  --output result.pdf
  # 💡 Linux: replace "base64 -i webpage.html" with "base64 -w 0 webpage.html"

DOCX to PDF

Carbone converts DOCX to PDF using LibreOffice ("converter": "L") for speed and general compatibility, or OnlyOffice ("converter": "O") for maximum fidelity on documents.

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 "{
    "data": {},
    "template": "$(base64 -i document.docx)",
    "convertTo": "pdf",
    "converter": "L"
  }" \
  --output result.pdf
  # 💡 Linux: 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 "{
    "data": {},
    "template": "$(base64 -i presentation.pptx)",
    "convertTo": "pdf",
    "converter": "L"
  }" \
  --output result.pdf
  # 💡 Linux: replace "base64 -i presentation.pptx" with "base64 -w 0 presentation.pptx"

PPTX to PNG

Render each slide of a presentation as a PNG image. Useful for CMS previews, document library thumbnails, or social media exports. The same request works for ODP inputs. Use formatOptions to control output dimensions and color mode (see JPG/PNG 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 "{
    "data": {},
    "template": "$(base64 -i presentation.pptx)",
    "convertTo": "png"
  }" \
  --output slide.png
  # 💡 Linux: replace "base64 -i presentation.pptx" with "base64 -w 0 presentation.pptx"

XLSX to PDF

Convert an Excel spreadsheet to a fixed-layout PDF. Useful for billing statements, financial reports, or client deliverables. 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 "{
    "data": {},
    "template": "$(base64 -i spreadsheet.xlsx)",
    "convertTo": "pdf",
    "converter": "L"
  }" \
  --output result.pdf
  # 💡 Linux: replace "base64 -i spreadsheet.xlsx" with "base64 -w 0 spreadsheet.xlsx"

XLSX to CSV

Export a spreadsheet as plain-text CSV for use in data pipelines, database imports, or downstream processing. By default, Carbone uses a comma separator and UTF-8 encoding. Use formatOptions to change the field separator, text delimiter, or character encoding (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 "{
    "data": {},
    "template": "$(base64 -i spreadsheet.xlsx)",
    "convertTo": "csv"
  }" \
  --output result.csv
  # 💡 Linux: replace "base64 -i spreadsheet.xlsx" with "base64 -w 0 spreadsheet.xlsx"

XLSX to JSON

Export a spreadsheet as JSON for data pipelines, API integrations, or downstream processing. Each row is converted to a JSON object, making it easy to ingest spreadsheet data directly into your application.

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 "{
    "data": {},
    "template": "$(base64 -i spreadsheet.xlsx)",
    "convertTo": "json"
  }" \
  --output result.json
  # 💡 Linux: replace "base64 -i spreadsheet.xlsx" with "base64 -w 0 spreadsheet.xlsx"

XLSX to Parquet

Export a spreadsheet to Apache Parquet format for use in data engineering pipelines and analytics platforms. Parquet's columnar storage makes it the preferred input format for Spark, AWS Athena, Google BigQuery, Snowflake, and Databricks.

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 "{
    "data": {},
    "template": "$(base64 -i spreadsheet.xlsx)",
    "convertTo": "parquet"
  }" \
  --output result.parquet
  # 💡 Linux: replace "base64 -i spreadsheet.xlsx" with "base64 -w 0 spreadsheet.xlsx"

MD to PDF

Convert a Markdown file to PDF. Carbone is the conversion layer between AI-generated Markdown and the PDFs your users receive.

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 "{
    "data": {},
    "template": "$(base64 -i document.md)",
    "convertTo": "pdf",
    "converter": "L"
  }" \
  --output result.pdf
  # 💡 Linux: replace "base64 -i document.md" with "base64 -w 0 document.md"

MD to DOCX

Converts Markdown to DOCX server-side, making it the conversion layer between your AI or documentation pipeline and the Word documents your recipients expect.

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 "{
    "data": {},
    "template": "$(base64 -i document.md)",
    "convertTo": "docx",
    "converter": "L"
  }" \
  --output result.docx
  # 💡 Linux: replace "base64 -i document.md" with "base64 -w 0 document.md"

DOCX to MD

Extracts DOCX content as Markdown file, making it ready for LLM ingestion, vector embedding, RAG pipelines, or static site generators — no manual copy-paste. Uses the md output format.

curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
  --header 'carbone-version: 5' \n  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_TOKEN' \
  --data-raw "{
    "data": {},
    "template": "$(base64 -i document.docx)",
    "convertTo": "md",
    "converter": "L"
  }" \
  --output result.md
  # 💡 Linux: replace "base64 -i document.docx" with "base64 -w 0 document.docx"

PDF to PDF

Re-export a PDF with security or compliance options applied. Password protection, watermarks, PDF/A archival compliance, page range selection, print permissions, accessibility tags (PDF/UA), document open settings, image compression, and more. All use the same formatOptions object and can be combined in a single call. See PDF options for the full list of available settings.

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 "{
    "data": {},
    "template": "$(base64 -i document.pdf)",
    "convertTo": {
      "formatName": "pdf",
      "formatOptions": {
        "Watermark": "CONFIDENTIAL",
        "EncryptFile": true,
        "DocumentOpenPassword": "s3cr3t",
        "SelectPdfVersion": 3
      }
    },
    "converter": "L"
  }" \
  --output protected.pdf
  # 💡 Linux: replace "base64 -i document.pdf" with "base64 -w 0 document.pdf"