---
source: https://carbone.io/documentation/developer/http-api/convert-reports.html
title: "Convert Documents"
description: "HTTP API to convert documents between 100+ formats in a single API call"
generated_at: "2026-07-13"
---

# 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 pages or web-based content 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](https://carbone.io/documentation/developer/http-api/generate-reports.md#output-file-type) for all supported input/output format combinations.

## Convert a Document

POST /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](/documentation/developer/http-api/generate-reports.md)

### Request headers

```json
{
    // 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"
}
```

### Request body

```jsonc
{
  // 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 (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](/documentation/developer/http-api/generate-reports.md#output-file-type) 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](/documentation/developer/http-api/generate-reports.md#direct-download)).   `false`: returns a JSON object with a `renderId`; use `GET /render/{renderId}` to download the file in a second call ([see Download Reports](/documentation/developer/http-api/download-reports.md)). |

### 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"" }` |
| 🔴 | 401 | `{ "success": false, "error": "Unauthorized, please provide a valid API key" }` |
| 🔴 | 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": "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.

```bash
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 page as an image with the Chromium engine (`"converter": "C"`). Convert HTML to `png`, `jpg`, or `webp` - useful for social share cards, previews, or embedding web-based snapshots in apps.

```bash
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\": \"png\",
        \"converter\": \"C\"
      }" \
      --output result.png
```

> 💡 **Linux users**: 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.

```bash
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).

```bash
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 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](/documentation/developer/http-api/generate-reports.md#jpg-png-options)).

```bash
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 a fixed-layout PDF. Useful for billing statements, financial reports, or client deliverables. The same request works for ODS.

```bash
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 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](/documentation/developer/http-api/generate-reports.md#csv-options)).

```bash
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. Carbone is the conversion layer between AI-generated Markdown and the PDFs your users receive.

```bash
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

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

```bash
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

Extracts DOCX content as a 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.

```bash
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 an image. Convert a PDF to `png`, `jpg`, or `webp` - useful for thumbnails, previews, or embedding document snapshots in web and mobile apps. Use `formatOptions` to control output dimensions and quality (see [JPG/PNG options](/documentation/developer/http-api/generate-reports.md#jpg-png-options)).

```bash
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 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](/documentation/developer/http-api/generate-reports.md#pdf-options) for the full list of available settings.

### Password protection

```bash
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)

```bash
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`

## Related topics

- [Upload and manage templates](/documentation/developer/http-api/manage-templates.md)
- [Introduction](/documentation/developer/http-api/introduction.md)
- [Generate reports](/documentation/developer/http-api/generate-reports.md)
- [Download Generated Reports](/documentation/developer/http-api/download-reports.md)