---
source: https://carbone.io/documentation/developer/http-api/introduction.html
title: "Introduction to Carbone APIs"
description: "Setting up Carbone APIs. Use our turnkey APIs to generate all types of documents and reports."
generated_at: "2026-07-07"
---

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

> ℹ️ **Note:** 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](/documentation/quickstart/integration/for-developers.md)

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

-   [**Postman Carbone V5**](https://www.postman.com/carbone-official/carbone-io)
-   [**OpenAPI Carbone V5**](/file/carbone.OpenAPI.yml)
-   [**Insomnia Carbone V5**](/file/carbone.Insomnia.yml)

## Requirements

**Carbone Cloud:**

1.  [Create or sign in](https://account.carbone.io/) 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:**

-   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

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

```json
{
  "authorization": "Bearer YOUR_API_TOKEN"
}
```

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

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

-   `{renderId}` is a cryptographically random, unique identifier - it acts as a single-use password per rendered document, stronger than a traditional auth mechanism.
-   `{renderId}` is ephemeral: the resource becomes inaccessible once the file is downloaded or after one hour.
-   This allows the document to be downloaded directly in any browser, reverse proxy, or application without complex authentication.

For Carbone Cloud, authentication is mandatory. Your API key is available on the home page of your [Carbone account](https://account.carbone.io/).

For on-premise deployments, authentication is disabled by default. To enable it, see the [authentication configuration](/documentation/developer/on-premise-installation/configuration.md#authentication).

## 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`](/documentation/developer/http-api/manage-templates.md#upload-a-template) - returns a `templateId`.
2.  Render from the `templateId` and a JSON dataset with [`POST /render/{templateId-or-versionId}`](/documentation/developer/http-api/generate-reports.md) - returns a `renderId`.
3.  Download the document with [`GET /render/{renderId}`](/documentation/developer/http-api/download-reports.md).
4.  Reuse the same `templateId` for every new document (repeat from step 2).

**Tip:** add [`?download=true`](/documentation/developer/http-api/generate-reports.md#direct-download) 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`](/documentation/developer/http-api/generate-reports.md#providing-a-template). 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](#api-webhook) (a 5-minute timeout instead of 60 seconds).

Test the API with the [Carbone Cloud API quickstart](/documentation/quickstart/getting-started/generate-a-document.md).

## Template ID

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

-   **Version Control:** Multiple versions of a template can be associated with a single Template ID.
-   **Generation:** Carbone automatically selects the version of the template that is marked as deployed (i.e., the version with the most recent `deployedAt` timestamp field). If no version is marked as deployed, the latest version is used.
-   **Backward Compatibility:** If versioning is disabled or undefined, the system returns and uses the "templateId" as a SHA-256 hash of the template file.

## 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}`](/documentation/developer/http-api/generate-reports.md) when `download` is `false`, and is used to download the document with [`GET /render/{renderId}`](/documentation/developer/http-api/download-reports.md).

-   **Single-use and ephemeral:** the document and its `renderId` are available for one hour and can be downloaded only once (see [Report storage](#report-storage)).
-   **No authentication required:** because the `renderId` is unguessable and short-lived, [`GET /render/{renderId}`](/documentation/developer/http-api/download-reports.md) is not protected, so the file can be fetched directly from a browser, reverse proxy, or application (see [Authentication](#authentication)).

## 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](#template-id).

For Carbone Cloud, the template storage retention behaves 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 setting the `expireAt` field when uploading with `POST /template`.
-   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](https://help.carbone.io/en-us/article/everything-about-template-storage-12ppn8u/).

## 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:

-   The document is downloaded.
-   After one hour.

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:

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

If a timeout is thrown, consider using asynchronous rendering with [webhooks](#api-webhook); 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:
    
    ```json
    {
    "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:
    
    ```json
    { 
    "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

> ℹ️ **Note:** 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:

-   `5`: [changelog v5.0.0](/changelog.md#v5-0-0) (**latest version, recommended**)
-   `4`: [changelog v4.0.0](/changelog.md#v4-0-0) (default)
-   `3`: [changelog v3.0.0](/changelog.md#v3-0-0)
-   `staging`: not intended for production environments

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](/documentation/developer/on-premise-installation/upgrade-guide.md#breaking-changes).

## 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](/integration/index.md), or jump straight to one:

| Category | Integrations |
| --- | --- |
| **SDKs** | [Node.js](/documentation/developer/api-sdks/nodejs.md), [JavaScript](/documentation/developer/api-sdks/javascript.md), [PHP](/documentation/developer/api-sdks/php.md), [Python](/documentation/developer/api-sdks/python.md), [Go](/documentation/developer/api-sdks/go.md), [Java](/documentation/developer/api-sdks/java.md), [Rust](/documentation/developer/api-sdks/rust.md) |
| **Automation & no-code** | [Airtable](/integration/airtable.md), [Bubble](/integration/bubble.md), [Glide](/integration/glide.md), [Make](/integration/make.md), [n8n](/integration/n8n.md), [Ninox](/integration/ninox.md), [Retool](/integration/retool.md), [Zapier](/integration/zapier.md) |
| **CRM & business** | [HubSpot](/integration/hubspot.md), [Odoo](/integration/odoo.md), [Pipedrive](/integration/pipedrive.md), [Salesforce](/integration/salesforce.md) |
| **E-signature** | [DocuSign](/integration/docusign.md), [Subnoto](/integration/subnoto.md) |
| **AI assistants** | [ChatGPT](/integration/chatgpt.md), [Claude](/integration/claude.md), [Cursor](/integration/cursor.md), [DeepSeek](/integration/deepseek.md), [Gemini](/integration/gemini.md), [Grok](/integration/grok.md), [Llama](/integration/llama.md), [Microsoft Copilot](/integration/copilot.md), [Vibe by Mistral](/integration/vibe.md) |

## Related topics

- [Upload and manage templates](/documentation/developer/http-api/manage-templates.md)
- [Generate reports](/documentation/developer/http-api/generate-reports.md)
- [Download Generated Reports](/documentation/developer/http-api/download-reports.md)
- [Convert Documents](/documentation/developer/http-api/convert-reports.md)