convert_document

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "minLength": 1,
      "description": "The document to convert. Two input forms are accepted: (1) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (2) Base64-encoded string — the raw file content encoded as base64. Local file paths are NOT accepted — this server is reached over HTTP, so a path would resolve on the server's disk rather than yours and is rejected. Upload the bytes as base64, or host the file at a URL. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown (MD), TXT, CSV, RTF, PDF, PNG and JPG. Carbone reads XML-based and text-based documents only, so the legacy BINARY Office formats DOC, XLS and PPT are REJECTED as input — Carbone can produce them as output but cannot read them. Re-save such a file as DOCX/XLSX/PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md"
    },
    "convertTo": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "pdf",
            "docx",
            "doc",
            "xlsx",
            "xls",
            "pptx",
            "ppt",
            "odt",
            "ods",
            "odp",
            "odg",
            "html",
            "xhtml",
            "txt",
            "csv",
            "md",
            "xml",
            "rtf",
            "png",
            "jpg",
            "jpeg",
            "webp",
            "svg",
            "tiff",
            "bmp",
            "gif",
            "zip",
            "idml",
            "epub",
            "cdr"
          ]
        },
        {
          "type": "object",
          "properties": {
            "formatName": {
              "type": "string",
              "enum": [
                "pdf",
                "docx",
                "doc",
                "xlsx",
                "xls",
                "pptx",
                "ppt",
                "odt",
                "ods",
                "odp",
                "odg",
                "html",
                "xhtml",
                "txt",
                "csv",
                "md",
                "xml",
                "rtf",
                "png",
                "jpg",
                "jpeg",
                "webp",
                "svg",
                "tiff",
                "bmp",
                "gif",
                "zip",
                "idml",
                "epub",
                "cdr"
              ],
              "description": "Target format name."
            },
            "formatOptions": {
              "description": "Advanced format options object. Examples by format: PDF — { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\", \"DocumentPermissionPassword\": \"owner\" } password-protect; PDF — { \"Watermarks\": [{ \"text\": \"DRAFT\", \"opacity\": 0.2, \"rotation\": -45, \"fontsize\": 60 }] } up to 5 watermarks; PDF — { \"SelectPdfVersion\": 1 } PDF/A-1b compliance (use 2 for PDF/A-2, 3 for PDF/A-3); PDF — { \"PageRange\": \"1-3,5\" } export specific pages only; PDF — { \"ConvertSlideshow\": true } convert each slide to a separate PDF page; Images (PNG/JPG/WEBP) — { \"Quality\": 90 } set compression quality 0-100; Images — { \"density\": 150 } set DPI for rasterisation (default 96); CSV — { \"fieldSeparator\": \";\" } custom column separator.",
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {}
            }
          },
          "required": [
            "formatName"
          ]
        }
      ],
      "description": "Target output format. Documents : \"pdf\", \"docx\", \"xlsx\", \"pptx\", \"odt\", \"ods\", \"odp\", \"odg\", \"rtf\", \"epub\", plus the legacy \"doc\", \"xls\", \"ppt\" (output only — Carbone writes them but cannot read them back). Web/text  : \"html\", \"xhtml\", \"txt\", \"csv\", \"md\", \"xml\", \"idml\". Images    : \"png\", \"jpg\", \"jpeg\", \"webp\", \"svg\", \"tiff\", \"bmp\", \"gif\". Archive   : \"zip\" (batch output). Simple usage: \"pdf\". Advanced usage: { \"formatName\": \"pdf\", \"formatOptions\": { \"EncryptFile\": true, \"DocumentOpenPassword\": \"secret\" } }."
    },
    "converter": {
      "description": "Converter engine. Only relevant when convertTo is \"pdf\" (or an image format rasterised from a document). \"L\" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. \"O\" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). \"C\" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. \"I\" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick \"I\" when the request needs a password or restricted permissions; use \"L\" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default.",
      "type": "string",
      "enum": [
        "L",
        "C",
        "O",
        "I"
      ]
    },
    "reportName": {
      "description": "Filename (WITHOUT extension) for the converted document, returned in the Content-Disposition header. Carbone appends the extension matching convertTo, so do not include one — \"report.pdf\" yields \"report.pdf.pdf\". Examples: \"contract\", \"2026-invoice\". Unlike render_document, Carbone tags are NOT resolved here (conversion does not run templating), so pass a literal name rather than a pattern like \"{d.id}\" — a pattern would come back verbatim. Ignored when returnLink is set, which returns a download URL rather than a named file.",
      "type": "string"
    },
    "hardRefresh": {
      "description": "Forces Carbone to run the converter even when the output format already matches the input format. Only useful for PDF: converting PDF → PDF to APPLY formatOptions (watermark, password, PDF/A, page range). Without it Carbone may pass the file straight through and none of those options take effect. Leave unset for any format-changing conversion (DOCX → PDF, XLSX → CSV, …), where the converter runs anyway.",
      "type": "boolean"
    },
    "outputPath": {
      "description": "NOT AVAILABLE on this server, which is reached over HTTP: the converted document would be written to the server's disk instead of yours, so passing outputPath is rejected. Use asAttachment to receive the bytes, or returnLink for a one-time download URL.",
      "type": "string"
    },
    "asAttachment": {
      "description": "If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.",
      "type": "boolean"
    },
    "returnLink": {
      "description": "If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment.",
      "type": "boolean"
    },
    "egressAuthorization": {
      "description": "Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example \"Bearer abc123\" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 512 characters.",
      "type": "string",
      "maxLength": 512
    }
  },
  "required": [
    "file",
    "convertTo"
  ]
}