---
source: https://carbone.io/documentation/developer/api-sdks/go.html
title: "Generate your reports with Go SDK"
description: "Generate report with Go"
generated_at: "2026-07-08"
---

# Go SDK

Generate report with Go

Golang SDK to generate reports through the [Carbone Cloud API](/documentation/quickstart/getting-started/generate-a-document.md) in a few lines of code.

The source code is available on Github: [https://github.com/carboneio/carbone-sdk-go](https://github.com/carboneio/carbone-sdk-go)

## Install

```sh
go get github.com/carboneio/carbone-sdk-go
```

## Quickstart

Try the following code to generate a report in a few seconds. Insert an API key, provide the template, and the data as a stringified JSON, that's it.

```go
package main

import (
    "io/ioutil"
    "log"

    "github.com/carboneio/carbone-sdk-go/carbone"
)

func main() {
    csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
    if err != nil {
        log.Fatal(err)
  }
  // Path to your template
  templateID := "./folder/template.odt"
  // Add your data here
    jsonData := `{"data":{},"convertTo":"pdf"}`
    reportBuffer, err := csdk.Render(templateID, jsonData)
    if err != nil {
        log.Fatal(err)
    }
    err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
    if err != nil {
        log.Fatal(err)
    }
}
```

## Constructor

```go
func NewCarboneSDK(SecretAccessToken ...string) (*CSDK, error)
```

Function to create a new instance of CSDK (CarboneSDK). The access token can be passed as an argument to NewCarboneSDK (`args[0]`) or by the environment variable "CARBONE\_TOKEN". To set a new environment variable, use the command:

```bash
$ export CARBONE_TOKEN=your-secret-token
```

Check if it is set by running:

```bash
$ printenv | grep "CARBONE_TOKEN"
```

Example

```go
// Carbone access token passed as parameter
csdk, err := carbone.NewCarboneSDK("YOUR-ACCESS-TOKEN")
// Carbone access token passed as environment variable "Carbone TOKEN"
csdk, err := carbone.NewCarboneSDK()
```

## Generate a report

```go
func (csdk *CSDK) Render(pathOrTemplateID string, jsonData string, payload ...string) ([]byte, error)
```

The render function takes `pathOrTemplateID` the path of your local file OR a templateID, `jsonData` a stringified JSON, and an optional `payload`.

It returns the report as a `[]byte`. Carbone engine deletes files that have not been used for a while. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.

When a **template file path** is passed as an argument, the function verifies if the template has been uploaded to render the report. If not, it calls [AddTemplate](#upload-a-template) to upload the template to the server and generate a new template ID. Then it calls [RenderReport](#generate-a-report) and GetReport to generate the report. If the path does not exist, an error is returned.

When a **templateID** is passed as an argument, the function renders with [RenderReport](#generate-a-report) then calls GetReport to return the report. If the templateID does not exist, an error is returned.

**Example**

```go
reportBuffer, err := csdk.Render("./templates/invoice.docx", `{"data":{"name":"eric"},"convertTo":"pdf"}`, "OptionalPayload1234")
if err != nil {
    log.Fatal(err)
}
// create the file
err = ioutil.WriteFile("Report.pdf", reportBuffer, 0644)
if err != nil {
    log.Fatal(err)
}
```

## Upload a template

```go
func (csdk *CSDK) AddTemplate(templateFileName string, payload ...string) (APIResponse, error)
```

Adds the template to the API and returns an `APIResponse` struct (that contains a `TemplateID`). You can add multiple times the same template and get a different templateId thanks to the optional `payload`.

**Example**

```go
resp, err := csdk.AddTemplate("./tests/template.test.odt")
if err != nil {
    t.Error(err)
}
if resp.Success == false {
    t.Error(resp.Error)
}
if len(resp.Data.TemplateID) <= 0 {
    t.Error(errors.New("templateId not returned from the api"))
}
fmt.Println("templateID:", resp.Data.TemplateID)
```

## Download a template

```go
func (csdk *CSDK) GetTemplate(templateID string) ([]byte, error)
```

Pass a `templateID` to the function and it returns the template as `[]byte`. The templateID must exist; otherwise, an error is returned by the server.

```go
    templateData, err := csdk.GetTemplate("TemplateId")
    if err != nil || len(templateData) <= 0 {
        t.Error(err)
    }
    err = ioutil.WriteFile(filename, templateData, 0644)
    if err != nil {
        t.Error(err)
    }
```

## Delete a template

```go
func (csdk *CSDK) DeleteTemplate(templateID string) (APIResponse, error)
```

**Example**

```go
resp, err := csdk.DeleteTemplate(templateID)
if err != nil {
    t.Error(err)
}
if resp.Success == false {
    t.Error(resp.Error)
}
```

## Generate a template ID

```go
func (csdk *CSDK) GenerateTemplateID(filepath string, payload ...string) (string, error)
```

The Template ID is predictable and idempotent, pass the template path and it will return the `templateID`. You can get a different templateId thanks to the optional `payload`.

## API Token

```go
func (csdk *CSDK) SetAccessToken(newToken string)
```

It sets the Carbone access token.

## Carbone API version

**Set**

```go
func (csdk *CSDK) SetAPIVersion(version int)
```

It sets the Carbone version requested. By default, it is calling the version `2` of Carbone.

_Note:_ You can only set a major version of carbone.

**Get**

```go
func (csdk *CSDK) GetAPIVersion() (int, error)
```

It returns the Carbone version.

## Related topics

- [Rust SDK](/documentation/developer/api-sdks/rust.md)
- [Python SDK](/documentation/developer/api-sdks/python.md)
- [PHP SDK](/documentation/developer/api-sdks/php.md)
- [NodeJS SDK](/documentation/developer/api-sdks/nodejs.md)
- [Javascript SDK](/documentation/developer/api-sdks/javascript.md)
- [Java SDK](/documentation/developer/api-sdks/java.md)