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:

Create a Carbone Cloud account or sign-in: https://account.carbone.io/
For testing purposes, use a test API token: Generate unlimited watermarked PDFs for free (Only PDF file format).
For production purposes, use a production API token: Generate any document formats without a watermark. The free Sandbox Plan plan is available, giving you 100 credits per month. If you need more credits, you can upgrade your subscription.

Carbone On-Premise:

Start the service!
Open the status page in your browser http://your-ip:port/status to check it is running

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

Authentication

The API token must be passed for all APIs:

{
  "authorization": "Bearer YOUR_API_TOKEN",
}

All API endpoints are protected by authentication except GET /render/:renderId and GET /status.

Reasons why GET /render/:renderId is not protected:

:renderId contains the custom report name in base64, concatenated with a 22-characters-long cryptographically random numbers with unbiased tranformation. It is somehow a unique password for each rendered report. It is better than any authentication mechanism.
:renderId is ephemeral, the resource becomes inaccessible once the file is downloaded.
The report can be easily downloaded in any browsers / reverse-proxy / application without complex authentication mechanisms

For on premise deployment, authentification is disable by default. To unable it, please follow this documentation.

API Flow

To generate a document, you have to:

Upload a template to get a template ID. The template is stored in the template storage.
Generate a report from the template ID and a JSON dataset, then the request returns a unique usable render ID.
Download the report thanks to the render ID.
To get a new document, repeat the process from point 2.

Test the API with Carbone Cloud API quickstart

Template ID

The Template ID is predictable and idempotent SHA256 hash, computed from the template content in hexadecimal. NodeJS example:

const crypto = require('crypto');

const hash = crypto.createHash('sha256')
                 .update('FILE_CONTENT')
                 .digest('hex');

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:

When a template is uploaded with a production token, it is stored for an unlimited time on your template storage. It is possible to upload a non-persistent template that will be deleted automatically by adding the header carbone-template-delete-after with days in seconds (86400s = 1 day, max 30 days).
When a template is uploaded with a test token, it is deleted automatically within 30 days.

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:

The document is downloaded.
After one hour.

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:

More than a hundred PDF pages are rendered
High-quality images.
Many pages and many images.

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

An asynchronous rendering is available, Carbone will notify your application/service at a custom URL as soon as the document is generated. For webhooks, the rendering timeout default value is 5 minutes. To enable it:

On your server, add webhook endpoint listening to a POST request.
When generating a report with the request POST /render/:templateId, add the header carbone-webhook-url with your webhook URL as a value.
You can customize the webhook headers by setting carbone-webhook-header-X header in the request POST /render/:templateId
For exemple, to add authentification for your webhook, you should add carbone-webhook-header-authorization: my-secret in render report call. The header authorization: my-secret will be added when Carbone calls the webhook.

API Version

Only for Carbone Cloud

By default, HTTP requests target the latest version of the Cloud API. It is recommended to specify an API version by providing the HTTP header carbone-version, such as: { "carbone-version": 4 }. Supported values:

staging: do not use for your production environment
5: changelog v5.0.0 beta version
4: changelog v4.0.0 latest version
3: changelog v3.0.0
2: changelog v2.0.0

Only a major version can be specified, and it will include all upcoming minor versions or patches.

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' : '4'
  }
}, (err, response, body) => {
  // Handle error
  // Body contains a response
});