> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for Carbone: every `carbone.api.*` operation with input and output types.

Every `carbone.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

<Info>
  **New to Corsair?** See [API access](/concepts/api), [authentication](/concepts/auth), and [error handling](/concepts/error-handling).
</Info>

## Render

### generateReport

`render.generateReport`

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

**Risk:** `write`

```ts theme={null}
await corsair.carbone.api.render.generateReport({
	templateId: 'tmpl_1234567890abcdef',
	data: { customer: 'Acme Corp', amount: 1250 },
	convertTo: 'pdf',
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string` | Yes | 64-character hexadecimal template ID or version ID to render |
| `data` | `object[]` | No | JSON dataset to merge into the document template placeholders |
| `convertTo` | `object` | No | Target file format extension to convert output document into (e.g. pdf, docx, xlsx, html) |
| `converter` | `string` | No | Converter engine to use for document conversion |
| `lang` | `string` | No | Localization language code for formatting numbers, dates, and currency (e.g. en-US, fr-FR) |
| `timezone` | `string` | No | IANA timezone string for date/time calculations (e.g. Europe/Paris, America/New\_York) |
| `currency` | `string` | No | ISO 4217 currency code for currency formatters (e.g. USD, EUR) |
| `translations` | `object` | No | Dictionary of translation strings per locale |
| `enum` | `object` | No | Enum mapping dictionaries for translating code values |
| `variable` | `object` | No | Pre-calculated variables accessible globally within the template |
| `complement` | `object` | No | Complementary dataset accessible with the c. prefix in templates |
| `hardRefresh` | `boolean` | No | When true, recalculates all template functions and forces fresh render |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
    } | lazy[]
    ```
  </Accordion>

  <Accordion title="convertTo full type">
    ```ts theme={null}
    string | {
      formatName: string,
      formatOptions?: {
      }
    }
    ```
  </Accordion>

  <Accordion title="translations full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="enum full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="variable full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="complement full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if report generation succeeded |
| `data` | `object` | Yes | Render result payload containing the render ID |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      renderId: string
    }
    ```
  </Accordion>
</AccordionGroup>

***

### renderDirect

`render.renderDirect`

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.

**Risk:** `write`

```ts theme={null}
await corsair.carbone.api.render.renderDirect({
	template: 'UEsDBBQAAAAIAAAAIQAAAAAAAAAAAAAAAAAJAAAAdGVtcGxhdGUuZG9jeA==',
	data: { customer: 'Acme Corp', amount: 1250 },
	convertTo: 'pdf',
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `template` | `string` | Yes | Base64-encoded document template content |
| `data` | `object[]` | No | JSON dataset to merge into the template placeholders |
| `convertTo` | `object` | No | Target output document format extension (e.g. pdf, docx, xlsx, html) |
| `converter` | `string` | No | Converter engine to use for document conversion |
| `lang` | `string` | No | Localization language code for formatting numbers and dates |
| `timezone` | `string` | No | IANA timezone string for date operations |
| `currency` | `string` | No | ISO 4217 currency code for currency formatting |
| `translations` | `object` | No | Translation dictionaries for multi-language templates |
| `enum` | `object` | No | Enum dictionaries for code translation |
| `variable` | `object` | No | Pre-calculated variables accessible in template |
| `complement` | `object` | No | Complementary data accessible with c. prefix |
| `hardRefresh` | `boolean` | No | Force complete recalculation of document fields |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
    } | lazy[]
    ```
  </Accordion>

  <Accordion title="convertTo full type">
    ```ts theme={null}
    string | {
      formatName: string,
      formatOptions?: {
      }
    }
    ```
  </Accordion>

  <Accordion title="translations full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="enum full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="variable full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="complement full type">
    ```ts theme={null}
    {
    }
    ```
  </Accordion>
</AccordionGroup>

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if direct template rendering succeeded |
| `data` | `object` | Yes | Render result payload |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      renderId: string
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Status

### get

`status.get`

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

**Risk:** `read`

```ts theme={null}
await corsair.carbone.api.status.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if the status check request succeeded |
| `code` | `number` | No | HTTP status code returned by API |
| `message` | `string` | Yes | Status message from Carbone server |
| `version` | `string` | No | Active Carbone engine/API version |

***

## Templates

### delete

`templates.delete`

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.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.carbone.api.templates.delete({ templateId: 'tmpl_1234567890abcdef' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string` | Yes | 64-character hexadecimal template ID to permanently delete |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if template was successfully deleted |
| `message` | `string` | No | Confirmation message from Carbone server |

***

### download

`templates.download`

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

**Risk:** `read`

```ts theme={null}
await corsair.carbone.api.templates.download({ templateId: 'tmpl_1234567890abcdef' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string` | Yes | 64-character hexadecimal template ID to download |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string` | Yes | ID of the downloaded template |
| `content` | `string` | Yes | Base64-encoded binary content of the retrieved template file |
| `success` | `boolean` | Yes | Indicates if template download was successful |

***

### list

`templates.list`

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.

**Risk:** `read`

```ts theme={null}
await corsair.carbone.api.templates.list({ id: 'tmpl_1234567890abcdef', cursor: 0 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | No | Filter templates by exact template ID match |
| `templateId` | `string` | No | Alias for id; filter templates by exact template ID match |
| `versionId` | `string` | No | Filter templates by exact version ID match |
| `category` | `string` | No | Filter templates belonging to a specific category folder |
| `search` | `string` | No | Search templates by name or identifier query |
| `cursor` | `string \| number` | No | Pagination cursor for iterating through templates |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if listing templates succeeded |
| `data` | `object[]` | Yes | Array of deployed Carbone template metadata records |
| `hasMore` | `boolean` | No | Whether more template records are available on next page |
| `nextCursor` | `string \| number` | No | Cursor to retrieve the next page of templates |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      versionId?: string,
      id?: string | null,
      name?: string,
      category?: string,
      type?: string,
      size?: number,
      comment?: string,
      tags?: string[],
      deployedAt?: number | null,
      createdAt?: number,
      expireAt?: number | null,
      origin?: number
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### listCategories

`templates.listCategories`

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.

**Risk:** `read`

```ts theme={null}
await corsair.carbone.api.templates.listCategories({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if listing categories succeeded |
| `data` | `object[]` | Yes | List of category folder names used across templates |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      name: string
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### listTags

`templates.listTags`

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.

**Risk:** `read`

```ts theme={null}
await corsair.carbone.api.templates.listTags({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if listing tags succeeded |
| `data` | `object[]` | Yes | List of tag names used across templates |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      name: string
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### update

`templates.update`

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.

**Risk:** `write`

```ts theme={null}
await corsair.carbone.api.templates.update({
	templateId: 'tmpl_1234567890abcdef',
	name: 'Updated invoice template',
	category: 'Finance',
	tags: ['invoices', 'v2'],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `templateId` | `string` | Yes | 64-character hexadecimal template ID to update |
| `name` | `string` | No | Updated human-readable name of the template |
| `category` | `string` | No | Updated category folder for organizing the template |
| `comment` | `string` | No | Updated description or version release comment |
| `tags` | `string[]` | No | Updated array of tag strings for filtering |
| `deployedAt` | `number` | No | Unix timestamp to control version deployment |
| `expireAt` | `number` | No | Unix timestamp when the template will automatically expire |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if template metadata update succeeded |
| `data` | `object` | No | Updated metadata values of the template |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      name?: string,
      category?: string,
      comment?: string,
      tags?: string[],
      deployedAt?: number | null,
      versionId?: string,
      id?: string | null
    }
    ```
  </Accordion>
</AccordionGroup>

***

### upload

`templates.upload`

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.

**Risk:** `write`

```ts theme={null}
await corsair.carbone.api.templates.upload({ template: 'UEsDBBQAAAAIAAAAIQAAAAAAAAAAAAAAAAAJAAAAdGVtcGxhdGUuZG9jeA==' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `template` | `string` | Yes | Base64-encoded document template payload |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if template upload succeeded |
| `data` | `object` | Yes | Metadata of the newly uploaded template |

<AccordionGroup>
  <Accordion title="data full type">
    ```ts theme={null}
    {
      templateId?: string,
      id?: string,
      versionId?: string,
      templateExtension?: string,
      type?: string,
      size?: number,
      createdAt?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Version

### set

`version.set`

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.

**Risk:** `write`

```ts theme={null}
await corsair.carbone.api.version.set({ version: '5' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `version` | `string` | Yes | Carbone API major version string to use for subsequent requests (e.g. "5") |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | Indicates if setting API version was successful |
| `version` | `string` | Yes | The active Carbone API version now configured |
| `message` | `string` | Yes | Confirmation message |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.