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

There are two ways to generate a document:

Flow 1 — Template ID (recommended for production)

Best when you reuse the same template multiple times. The template is uploaded once and stored.

  1. Upload a template with POST /template to get a templateId
  2. Generate a document from the templateId and a JSON dataset with POST /render/:templateId — returns a renderId
  3. Download the document with GET /render/:renderId
  4. For new documents, repeat from step 2

Flow 2 — Single request (inline)

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

  1. Generate and download a document in a single request with POST /render/template?download=true — pass the template as base64 in the template body field along with your JSON dataset

Test the API with Carbone Cloud API quickstart

Template ID

A constant identifier for a template (format: 64-bit), and 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.

Template storage

Templates are your documents' base design. It 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 behave 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 render ID 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 render ID.

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 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 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.

Example

const request = require('request');
const fs      = require('fs');

const bearerToken = 'YOUR_TOKEN'
const templateId  = 'YOUR_TEMPLATE_ID';

request.delete({
  url : 'https://api.carbone.io/template/' + templatedId,
  headers : {
    'Authorization': 'Bearer ' + bearerToken,
    'carbone-version' : '5'
  }
}, (err, response, body) => {
  // Handle error
  // Body contains a response
});