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:

Carbone On-Premise:

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:

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:

  1. Upload a template to get a template ID. The template is stored in the template storage.
  2. Generate a report from the template ID and a JSON dataset, then the request returns a unique usable render ID.
  3. Download the report thanks to the render ID.
  4. 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');

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

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:

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
});