# Carbone

Carbone is a fast and simple report generator that converts JSON data into various document formats such as PDF, DOCX, XLSX, ODT, and more, using templates.

- **Category:** documents
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `CARBONE`
- **Version:** 20260312_00

## Tools

### Delete Carbone Template

**Slug:** `CARBONE_DELETE_TEMPLATE`

Permanently delete a template from the Carbone server by its 64-character hexadecimal template ID. This action is irreversible. Ensure you have the correct template ID before deleting.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `templateId` | string | Yes | The 64-character hexadecimal template ID (SHA-256 hash) to delete. Obtain this from the upload_template action response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Download Template

**Slug:** `CARBONE_DOWNLOAD_TEMPLATE`

Tool to download a template from Carbone by template ID. Use when you need to retrieve the original template file.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template_id` | string | Yes | The unique identifier (SHA256 hash) of the template to download. Obtain this from the upload template action or generate template ID action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Carbone Report

**Slug:** `CARBONE_GENERATE_REPORT`

Tool to generate a Carbone report from a template and JSON data. Use when you need to render documents in various formats.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data to merge into the template as a JSON object or an array of objects |
| `enum` | object | No | Enumerations to use with convEnum formatter, e.g. {'ORDER_STATUS': ['open', 'close']} |
| `lang` | string | No | Locale of the generated document, e.g. 'en-us' |
| `timezone` | string | No | Convert document dates to this timezone, e.g. 'Europe/Paris' |
| `convertTo` | string | No | Output file format as a string, e.g. 'pdf', or an object with formatName and formatOptions |
| `complement` | object | No | Extra data object merged into the template with tags {c.} |
| `reportName` | string | No | Static or dynamic file name returned in the content-disposition header, e.g. '{d.date}.odt' |
| `templateId` | string | Yes | Unique identifier of the Carbone template used to generate the report |
| `batchOutput` | string ("zip" | "pdf") | No | Output type for batch processing: 'zip' or 'pdf' |
| `hardRefresh` | boolean | No | Force recompute pagination and table of contents |
| `variableStr` | string | No | Predefined alias for template variables, e.g. '{#def = d.id}' |
| `batchSplitBy` | string | No | Batch processing split key, e.g. 'd.items' |
| `translations` | object | No | Localization dictionary for translations formatter, e.g. {'fr-ca': {'one': 'un'}} |
| `currencyRates` | object | No | Mapping of currency codes to exchange rates |
| `currencySource` | string | No | Currency source code for conversions, e.g. 'EUR' |
| `currencyTarget` | string | No | Target currency code for conversions, e.g. 'USD' |
| `carbone-webhook-url` | string | No | Webhook URL for asynchronous report generation. Include to enable async jobs. |
| `carbone-webhook-headers` | object | No | Custom headers for webhook calls, as a map of header name to value. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Carbone Server Status

**Slug:** `CARBONE_GET_STATUS`

Tool to retrieve the current status and health of the Carbone server. Use before generating reports to ensure the service is operational.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Template Categories

**Slug:** `CARBONE_LIST_TEMPLATE_CATEGORIES`

Tool to retrieve a list of all categories used in templates. Categories function like folders for organizing templates. Use when you need to see available template groupings.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `carbone_version` | integer | No | Carbone API version to use. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Templates

**Slug:** `CARBONE_LIST_TEMPLATES`

Tool to retrieve a list of templates from Carbone storage with filtering, search, and cursor-based pagination. Use when you need to find templates, search by name or ID, or iterate through all deployed templates.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | No | Filter by Template ID (64-bit format). Providing a Version ID (SHA256 format) is not allowed and will result in an API error. |
| `limit` | integer | No | Limit the number of items (100 by default). |
| `cursor` | string | No | A cursor to use in pagination. The cursor defines your place in the list for fetching the next set of results. |
| `origin` | integer ("0" | "1") | No | Template upload origin. |
| `search` | string | No | Search in template name (fuzzy search), Version ID (exact match), or Template ID (exact match). |
| `category` | string | No | Filter by category. |
| `versionId` | string | No | Filter by Version ID (SHA256 format). |
| `carbone_version` | integer | No | Carbone API version to use. |
| `includeVersions` | boolean | No | By default equals to false. Use true to list all versions for a specific template ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Template Tags

**Slug:** `CARBONE_LIST_TEMPLATE_TAGS`

Tool to list all tags currently used in templates. Use when you need to discover available tags for categorizing or filtering templates by document type or version.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `carbone_version` | integer | No | Carbone API version to use for this request. Defaults to 5. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Render Template Direct

**Slug:** `CARBONE_RENDER_TEMPLATE_DIRECT`

Tool to generate a document by uploading a base64-encoded template and data in a single API call. Use when you need to render documents without uploading templates separately.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data to merge into the template as a JSON object or an array of objects. Use {d.fieldname} placeholders in the template. |
| `enum` | object | No | Enumerations to use with convEnum formatter, e.g., {'ORDER_STATUS': ['open', 'close']} |
| `lang` | string | No | Locale of the generated document, e.g., 'en-us' |
| `download` | boolean | No | If true, returns the generated file directly. If false, returns a JSON response with renderId for async generation. |
| `template` | string | Yes | Base64-encoded template content. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML, or XML files. |
| `timezone` | string | No | Convert document dates to this timezone, e.g., 'Europe/Paris' |
| `convertTo` | string | No | Output file format as a string (e.g., 'pdf', 'docx'), or an object with formatName and formatOptions |
| `complement` | object | No | Extra data object merged into the template with tags {c.} |
| `reportName` | string | No | Static or dynamic file name returned in the content-disposition header, e.g., '{d.date}.odt' |
| `batchOutput` | string ("zip" | "pdf") | No | Output type for batch processing: 'zip' or 'pdf' |
| `hardRefresh` | boolean | No | Force recompute pagination and table of contents |
| `variableStr` | string | No | Predefined alias for template variables, e.g., '{#def = d.id}' |
| `batchSplitBy` | string | No | Batch processing split key, e.g., 'd.items' |
| `translations` | object | No | Localization dictionary for translations formatter, e.g., {'fr-ca': {'one': 'un'}} |
| `currencyRates` | object | No | Mapping of currency codes to exchange rates |
| `currencySource` | string | No | Currency source code for conversions, e.g., 'EUR' |
| `currencyTarget` | string | No | Target currency code for conversions, e.g., 'USD' |
| `carbone-version` | string | No | API version to use (3, 4, or 5). Specify this to override the default API version. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Carbone API Version

**Slug:** `CARBONE_SET_API_VERSION`

Tool to set the Carbone API version to be used for subsequent requests. Use before rendering or managing templates to ensure correct version is applied.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `version` | integer | Yes | Major Carbone API version (e.g., 4) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Template Metadata

**Slug:** `CARBONE_UPDATE_TEMPLATE`

Tool to update metadata and attributes of an existing Carbone template. Use when you need to modify template name, comment, tags, category, or control version deployment and lifecycle.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Template name to set or update. |
| `tags` | array | No | List of tags for organizing and filtering templates. |
| `comment` | string | No | Template comment or description for documentation purposes. |
| `category` | string | No | Group multiple templates into categories, similar to folders. |
| `expireAt` | integer | No | Delete the template at the specified time. Must be a UTC Unix timestamp. Values >= 42000000000 (year 3300) are treated as 'now'. Future timestamps are not allowed. |
| `deployedAt` | integer | No | When generating a document with a Template ID, Carbone uses the most recent deployedAt version. Must be a UTC Unix timestamp. Values >= 42000000000 (year 3300) are interpreted as 'NOW'. Future values are not allowed. |
| `templateId` | string | Yes | Unique identifier of the template or version ID to update. This is the 64-character hexadecimal template ID (SHA-256 hash). |
| `carbone_version` | integer | No | Carbone API version to use for this request. Defaults to 5. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload a template

**Slug:** `CARBONE_UPLOAD_TEMPLATE`

Upload a template file to the Carbone server to obtain a template ID for document generation. Supported template formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML, or XML. Templates can contain placeholders like {d.fieldname} that will be replaced with data during report generation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `template` | string | Yes | Template file to upload. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML, or XML files. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |