HTTP API

Introduction

Getting started with Carbone Cloud / On-Premise HTTP API

Overview

The HTTP API documentation is the same for both Carbone Cloud and Carbone On-Premise.

Using the API is the best solution to scale and generate reports from any applications, services, or languages.
To test the API quickly, go to the quickstart guide

To test the Cloud API in a few minutes, load a pre-made API specification into:

Requirements

Carbone Cloud:

  1. Create or sign in to your Carbone account
  2. Copy your API key from the home page of your account
  3. Choose the right token:
    • Test token - Generate unlimited watermarked PDFs for free (PDF format only)
    • Production token - Generate any document format without watermark. The free Sandbox Plan gives you 100 credits per month. Upgrade your subscription if you need more.

Carbone On-Premise:

By default, the authentication is disabled and the API is accessible as soon as the service is started.

Authentication

Pass your API token as a Bearer token in the Authorization header of every request:

{
  "authorization": "Bearer YOUR_API_TOKEN"
}

All endpoints require authentication except GET /render/{renderId} and GET /status.

Why GET /render/{renderId} is not protected:

For Carbone Cloud, authentication is mandatory. Your API key is available on the home page of your Carbone account.

For on-premise deployments, authentication is disabled by default. To enable it, see the authentication configuration.

API Flow

Carbone offers two ways to generate a document. Both accept the same JSON dataset and rendering options.

Flow 1 - Template ID (recommended for production)

Best when the same template is reused across many renders: upload it once, then render on demand.

  1. Upload the template once with POST /template - returns a templateId.
  2. Render from the templateId and a JSON dataset with POST /render/{templateId-or-versionId} - returns a renderId.
  3. Download the document with GET /render/{renderId}.
  4. Reuse the same templateId for every new document (repeat from step 2).

Tip: add ?download=true to step 2 to receive the file directly and skip step 3.

Flow 2 - Inline template (single request)

Best for one-off renders, conversions, or when you do not want to store the template.

Send the template as a base64 string in the template body field and render in a single call with POST /render/template?download=true. The template is not stored, and the generated file is returned directly in the response.

Need it asynchronous? For large reports or long-running renders, both flows support webhook-based asynchronous rendering (a 5-minute timeout instead of 60 seconds).

Test the API with the Carbone Cloud API quickstart.

Template ID

A constant identifier for a template (format: 64-bit), used to generate documents:

Version ID

A unique identifier for a specific version of a template (format: SHA-256 hash). The Version ID allows for precise control over template versions, including the ability to retrieve, update, and delete specific versions.

Render ID

A unique identifier for a generated document (format: a cryptographically random string). It is returned by POST /render/{templateId-or-versionId} when download is false, and is used to download the document with GET /render/{renderId}.

Template storage

Templates are your documents' base design. They will include static and dynamic content thanks to Carbone tags {d.value}. The Cloud subscription gives access to a storage space to store all your templates and identify them with a template ID.

For Carbone Cloud, the template storage retention behaves differently based on the API key:

Learn more about your template storage on the help center.

Report storage

When a document is generated thanks to a template ID and a JSON dataset, a renderId is provided to download a file. The document and URL are available for one hour, and can be downloaded one time.

They are deleted automatically when:

To get the same document, you must generate a new document and get a new renderId.

API Domain

The Carbone API base URL is https://api.carbone.io.

API Timeout

The rendering timeout default value is 60 seconds, and it may throw if the report contains:

If a timeout is thrown, consider using asynchronous rendering with webhooks; asynchronous rendering is 5 minutes.
If a generation is longer than 5 minutes, contact the support.

API Webhook

Carbone offers asynchronous rendering, notifying your application or service at a custom URL once the document is generated. The default rendering timeout for webhooks is set to 5 minutes. To enable this feature:

  1. Set Up Webhook Endpoint: On your server, create a webhook endpoint that listens for POST requests.
  2. Generate Report with Webhook: When generating a report using the POST /render/{templateId-or-versionId} request, include the carbone-webhook-url header with your webhook URL as the value. The response will contain the following body:
    {
"success": true,
"message": "A render ID will be sent to your callback URL when the document is generated"
}
  3. Customize Webhook Headers (Optional): You can customize the webhook headers by setting the carbone-webhook-header-X header in the POST /render/{templateId-or-versionId} request. For example, to add authentication for your webhook, include carbone-webhook-header-authorization: my-secret in the render report call. The header authorization: my-secret will be added when Carbone calls the webhook.
  4. Webhook Notification: Upon completion of the document generation, the webhook URL will be called with the following HTTP body:
    { 
"success": true, 
"data": { "renderId": "MTAuMjAuMTEuNDUgICAghMEQMbTlxkQYUWdRGoYotAcmVwb3J0.pdf" }
}
  5. Download Generated Document: Finally, the generated document can be downloaded using the renderId via the GET /render/{renderId} request.

API Version

Only for Carbone Cloud

It is recommended to specify an API version by using the carbone-version HTTP header, for example: { "carbone-version": "5" }. Supported values are:

Only a major version can be specified. This will automatically include all future minor versions and patches for that major version. Even though we strive to avoid breaking changes as much as possible, it is always a good practice to review our breaking changes guide.

Integrations

Prefer a ready-made connector or an SDK over hand-rolling HTTP calls? Carbone connects to your stack through official connectors and libraries. Browse the full integrations catalog, or jump straight to one:

Category Integrations
SDKs Node.js, JavaScript, PHP, Python, Go, Java, Rust
Automation & no-code Airtable, Bubble, Glide, Make, n8n, Ninox, Retool, Zapier
CRM & business HubSpot, Odoo, Pipedrive, Salesforce
E-signature DocuSign, Subnoto
AI assistants ChatGPT, Claude, Cursor, DeepSeek, Gemini, Grok, Llama, Microsoft Copilot, Vibe by Mistral