CAcarbone
Convert

Convert a document

Changed on

Convert your documents to 100+ formats, including PDF, ODT, DOCX, JPG, PNG, Markdown, CSV, ODS, XLSX, CSV, ODP, PPTX, XML, HTML, TXT, IDML, and many more. See the full conversion matrix for all supported input/output format combinations.

Two workflows are available for document conversion:

  1. Inline (base64): Send the document as a base64-encoded string in the request body field named "template". Use the special endpoint POST /render/template?download=true. No prior upload is needed.
  2. Pre-uploaded template: Upload the document once with POST /template, then convert it on demand using its templateId or versionId via POST /render/{templateId-or-versionId}?download=true.

Converters: set the converter field to L (LibreOffice, default), I (Carbone ICE, the fastest for DOCX/ODT to PDF), C (Chromium, for HTML) or O (OnlyOffice). See the converter field below and the converters documentation.

Notes:

  • Set the download query parameter to true to receive the converted file as a direct stream, or false (default) to receive a renderId for a separate GET /render/{renderId} download call.
  • For large files, set the carbone-webhook-url header: Carbone processes the conversion in the background and POSTs the result to your server when done.
post/render/template

Request

Query parameters

downloadboolean

Controls how the document is returned.

  • true: returns the 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}.
  • false: returns a JSON object with a renderId; use GET /render/{renderId} to download the file in a second call.

Headers

carbone-version'5' | '4' | '3' | 'staging' required

Carbone API major version to use. Only a major version can be specified: it automatically includes all future minor versions and patches.

  • 5: latest version, recommended.
  • 4: default when the header is not provided.
  • 3: legacy.
  • staging: not intended for production environments.

It is strongly recommended to always set this header explicitly to avoid unexpected behavior. See API versioning documentation

carbone-webhook-urlstring
Example:https://my-server.com/carbone-webhook

URL that Carbone calls (HTTP POST) when an asynchronous render or conversion finishes. Providing it enables asynchronous mode, which raises the rendering timeout to 5 minutes.

carbone-webhook-header-authorizationstring

Custom header forwarded on the webhook call only. It follows the carbone-webhook-header-<name> pattern, where any header <name> can be sent to your webhook (authorization is the most common). For the authorization header, this overrides carbone-egress-header-authorization for webhook calls.

carbone-egress-header-authorizationstring

Sets the authorization header Carbone sends on all egress traffic for this render: webhook calls, dynamic image URLs, and files fetched by appendFile. Example: carbone-egress-header-authorization: my-secret makes Carbone send authorization: my-secret on each outbound request. Only the authorization header can be customized, and the value must be shorter than 512 characters. For webhook calls, carbone-webhook-header-authorization overrides this value (webhook only).

Request body

templatestring required

Required for inline conversion. The source document encoded as a base64 string. Supported input formats: DOCX, XLSX, PPTX, PDF, ODT, ODS, ODP, ODG, TXT, CSV, HTML, XHTML, SVG, MD (Markdown), IDML, XML.

converter'L' | 'O' | 'C' | 'I'

Converter engine to use when a document format change is required (not only when convertTo is "pdf"). If omitted, LibreOffice (L) is used. See https://carbone.io/documentation/developer/http-api/generate-reports.html#converters

  • L LibreOffice (default): DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF. Best balance between performance and document compatibility, and the only converter supporting all PDF options.
  • I Carbone ICE (Instant Converter Engine): DOCX, ODT to PDF. The fastest converter, 3x to 300x faster than LibreOffice, OnlyOffice, or MS Word: Carbone draws the PDF itself, with no office suite involved. Only the Security and Watermark PDF options are supported. ODT to PDF is in beta. It can also be enabled per template with the {o.converter=I} tag. See limitations: https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations
  • C Chromium: HTML and XHTML to PDF, PNG, JPG/JPEG and WebP. SVG to PDF, PNG, JPG/JPEG and WebP. Image output options: PixelWidth, PixelHeight, FullPage, Scale, Quality. High-fidelity HTML conversion with full CSS support. JavaScript is disabled. Only the Security and Watermark PDF options are supported. 100 MB maximum document size.
  • O OnlyOffice: DOCX, XLSX, PPTX to PDF. Alternative for office documents. Only the Security and Watermark PDF options are supported. From v5.15.0, Carbone ICE is recommended instead of OnlyOffice for DOCX to PDF.
timezonestring

Convert document dates to a timezone. The date must be chained with the :formatD formatter. List of accepted timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

langstring

Locale of the generated document, used for translations {t()}, number formatting :formatN, and currencies :formatC. List of supported locales: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js

complementobject

Extra data accessible in the template with {c.} instead of {d.}.

variableStrstring

Predefined alias. See: https://carbone.io/documentation/design/substitutions/aliases.html#alias

reportNamestring

Static or dynamic output file name returned in the content-disposition header. The output extension is appended automatically, so do not include it. Supports multiple Carbone tags, e.g. {d.type}-{d.date}.

enumobject

List of enumerations for use with the convEnum formatter. See: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html#convenum-type

translationsobject

Localization dictionary used with {t( )} tags. Requires the lang option.

currencySourcestring

Source currency from your JSON data, used by formatC for currency conversion.

currencyTargetstring

Target currency for the generated document, used by formatC.

currencyRatesobject

Currency exchange rates for formatC conversion.

hardRefreshboolean

If true, recomputes pagination and table of contents at the end of rendering. It also forces a conversion when the output format is the same as the template format (for example XLSX to XLSX), to recompute spreadsheet formulas.

batchSplitBystring

Optional - Generate multiple reports with one template and an array of data, one report per object. "d" when data is itself an array of objects, or "d.myArray" to select a direct child array of data. Requires the carbone-webhook-url header (asynchronous mode) and a non-empty array of at most 100 objects on Carbone Cloud. Learn more: https://carbone.io/documentation/developer/http-api/generate-reports.html#batch-processing

batchOutput'zip' | 'pdf'

Optional (v5+) - Output file type for batch processing. zip (default) returns an archive of all the reports. pdf returns a concatenation of the generated PDFs, and requires convertTo to be pdf.

batchReportNamestring

Optional - Name of each file inside the ZIP batch export, Carbone tags accepted (e.g. report-{d.id}). Ignored when batchOutput is pdf. Used together with batchSplitBy. From v5.14.0, an index is appended to every file (report_1.pdf, report_2.pdf) as soon as the first two reports resolve to the same name.

preReleaseFeatureIninteger

Optional - Pre-release feature level for this render only. Only features and fixes introduced up to the given tag are applied, higher tags stay disabled. Learn more: https://carbone.io/documentation/design/overview/version-lifecycle.html#pre-release-features

failOnstring[]

Optional (v5.15.0+). Array of conditions that stop the render and return an error. IMAGE_URL_ERROR: an image that cannot be downloaded from its URL stops the report. It also applies to the Chromium converter, for PDF and image outputs: an image of an HTML page, or a resource of an SVG file, that cannot be downloaded stops the conversion. Learn more: https://carbone.io/documentation/developer/http-api/generate-reports.html#fail-on

Example request

{
  "template": "PCFET0NUWVBFIGh0bWw+...",
  "convertTo": "pdf",
  "converter": "L",
  "timezone": "Europe/Paris",
  "lang": "fr-fr",
  "complement": {},
  "variableStr": "{#def = d.id}",
  "reportName": "{d.date}",
  "enum": {},
  "translations": {
    "fr": {
      "one": "un"
    },
    "es": {
      "one": "uno"
    }
  },
  "currencySource": "EUR",
  "currencyTarget": "USD",
  "currencyRates": {
    "EUR": 1,
    "USD": 1.2
  },
  "batchSplitBy": "d.items",
  "batchOutput": "zip",
  "batchReportName": "report-{d.id}",
  "preReleaseFeatureIn": 5000000,
  "failOn": [
    "IMAGE_URL_ERROR"
  ]
}

Response

On success, by default a JSON response containing the renderId is returned. If the query parameter download=true is used, the response body is the converted/generated file stream and the Content-Type reflects the output format.

successboolean
messagestring

Returned only in asynchronous mode (carbone-webhook-url header set). The webhook URL is then called with { "success": true, "data": { "renderId": "..." } } once the document is generated.

Example response

{
  "data": {
    "renderId": "MTAuMjAuMjEuMTAgICAg.pdf"
  },
  "message": "A render ID will be sent to your callback URL when the document is generated"
}

Changes

  • c06cc573e3b0Revision changes
    • breaking

      the carbone-version request header's property undefined was restricted to a list of enum values

    • breaking

      the header request parameter carbone-version was restricted to a list of enum values

    • breaking

      for the query request parameter download, default value was changed from true to false

    • breaking

      request property was restricted to a list of enum values

    • breaking

      request property /// was restricted to a list of enum values

    • breaking

      request property /// was restricted to a list of enum values

    • breaking

      request property /// was restricted to a list of enum values

    • breaking

      request property /// was restricted to a list of enum values

    • breaking

      the /// request property type changed from number to integer

    • breaking

      the /// request property type changed from number to integer

    • warning

      the /// request property's max was set to 100.00

    • warning

      the /// request property's min was set to 0.00

    • info

      added the new optional header request parameter carbone-egress-header-authorization

    • info

      added the new optional header request parameter carbone-webhook-header-authorization

    • info

      added the new optional header request parameter carbone-webhook-url

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new enum value 3 to the header request parameter carbone-version

    • info

      added the new enum value 4 to the header request parameter carbone-version

    • info

      added the new enum value 5 to the header request parameter carbone-version

    • info

      added the new enum value staging to the header request parameter carbone-version

    • info

      for the header request parameter carbone-version, the type was generalized from integer to string, and format from int32 to no format

    • info

      the request property became optional

    • info

      the request property default value zip was added

    • info

      the request property default value L was added

    • info

      the request property default value 100 was removed

    • info

      added the new 0.00 enum value to the request property ///

    • info

      added the new 0.00 enum value to the request property ///

    • info

      added the new 0.00 enum value to the request property ///

    • info

      added the new 1.00 enum value to the request property ///

    • info

      added the new 1.00 enum value to the request property ///

    • info

      added the new 1.00 enum value to the request property ///

    • info

      added the new 1200.00 enum value to the request property ///

    • info

      added the new 15.00 enum value to the request property ///

    • info

      added the new 150.00 enum value to the request property ///

    • info

      added the new 16.00 enum value to the request property ///

    • info

      added the new 17.00 enum value to the request property ///

    • info

      added the new 2.00 enum value to the request property ///

    • info

      added the new 2.00 enum value to the request property ///

    • info

      added the new 2.00 enum value to the request property ///

    • info

      added the new 20.00 enum value to the request property ///

    • info

      added the new 3.00 enum value to the request property ///

    • info

      added the new 3.00 enum value to the request property ///

    • info

      added the new 300.00 enum value to the request property ///

    • info

      added the new 4.00 enum value to the request property ///

    • info

      added the new 4.00 enum value to the request property ///

    • info

      added the new 600.00 enum value to the request property ///

    • info

      added the new 75.00 enum value to the request property ///

    • info

      added the new I enum value to the request property

    • info

      added the new pdf enum value to the request property

    • info

      added the new zip enum value to the request property

    • info

      request property list-of-types was widened by adding types array to media type application/json

    • info

      the ///// request property's minLength was decreased from 1 to 0

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

  • fb25492a25ceRevision changes
    • info

      endpoint added