Go SDK quickstart

Last updated:

The American Cloud Go SDK is a typed client for the platform API, generated from the same OpenAPI document that drives the API itself. This page gets you from go get to a working program. For the bigger picture — how the three SDKs relate, the auth model, and supply-chain posture — see the SDKs overview.

Install

The module requires Go 1.21 or newer.

sh
go get github.com/American-Cloud/americancloud-sdk-go@latest

We recommend pinning an exact release and upgrading deliberately rather than tracking @latest:

sh
go get github.com/American-Cloud/[email protected]

Authenticate

Every request carries an API token in the Authorization: Bearer header. Create and manage tokens at console.americancloud.com/api-tokens. The token is shown once at creation — store it securely (an environment variable or secrets manager, never your repo). If it's lost, revoke the token and create a new one.

A token has the permissions you choose at creation: Read-only to list and price resources, Full access to create, change and delete them, or Custom to pick services one by one. Start with a Read-only token and create a Full access token when you're ready to create resources. client.Whoami.GetWhoami returns the permissions the token has now.

Pass the token to the client with option.WithToken, or set AMERICANCLOUD_API_TOKEN and omit the option. Reading it from the environment keeps secrets out of source:

sh
export AMERICANCLOUD_API_TOKEN="your-api-token"

SDK v1.8.0 and later take only a token. If you still use a legacy API key (client ID and secret), stay on v1.7.x or replace the key with a token.

First call: list regions

This complete program constructs a client and lists the regions you can deploy into — a read-only call, so a Read-only token is enough.

go
package main
 
import (
	"context"
	"fmt"
	"log"
	"os"
 
	americancloud "github.com/American-Cloud/americancloud-sdk-go/client"
	"github.com/American-Cloud/americancloud-sdk-go/option"
)
 
func main() {
	client := americancloud.NewClient(
		option.WithToken(os.Getenv("AMERICANCLOUD_API_TOKEN")),
	)
 
	regions, err := client.Regions.ListRegions(context.Background(), nil)
	if err != nil {
		log.Fatal(err)
	}
 
	for _, region := range regions.Data {
		fmt.Printf("%s — %s\n", region.Label, region.DisplayName)
	}
}

Every method takes a context.Context as its first argument, so requests participate in your timeouts and cancellation. The client is namespaced by resource — client.Regions, client.Vms, client.SSHKeys, client.DNSZones, client.BlockStorage, and so on.

[ go sdk · first call ]
Running the program above — real regions and your VM count, fully typed.

Estimate cost, then create a VM

You can preview pricing for an exact spec before committing to it. GetCostEstimateVms accepts the same body as create (CreateVMDto) and returns an estimate without provisioning anything. The create step needs a Full access token.

go
package main
 
import (
	"context"
	"fmt"
	"log"
	"os"
 
	americancloudsdkgo "github.com/American-Cloud/americancloud-sdk-go"
	americancloud "github.com/American-Cloud/americancloud-sdk-go/client"
	"github.com/American-Cloud/americancloud-sdk-go/option"
)
 
func main() {
	client := americancloud.NewClient(
		option.WithToken(os.Getenv("AMERICANCLOUD_API_TOKEN")),
	)
 
	ctx := context.Background()
 
	spec := &americancloudsdkgo.CreateVMDto{
		Name:      "web-01",
		Region:    "us-west-0",
		VMPackage: "standard-custom",
		Image:     "ubuntu-22.04",
		VMSpecs: &americancloudsdkgo.VMSpecsDto{
			Vcpu:       2,
			MemoryMb:   4096,
			RootDiskGb: 40,
		},
		SubscriptionPeriod: americancloudsdkgo.CreateVMDtoSubscriptionPeriodMonthly,
		Keypairs:           []string{"deploy-key"},
	}
 
	estimate, err := client.Vms.GetCostEstimateVms(ctx, spec)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Estimated monthly total: %.2f\n", estimate.Estimates.Monthly.Total)
 
	vm, err := client.Vms.CreateVms(ctx, spec)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Created VM %s (%s) — status %s\n", vm.ID, vm.Name, vm.Status)
}

Use real region, image, and vmPackage labels from client.Regions.ListRegions, client.Images.ListImages, and client.VMPackages.ListVMPackages. The estimate response also carries an optional BillingNote and DiscountApplied when applicable. CreateVMDto exposes more optional fields (tags, an attached Network, base64 cloud-init Userdata); the ones above are the minimum to provision.

Handle errors

Failed calls return an error you can match against typed values for each HTTP status — BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, InternalServerError, and GatewayTimeoutError. Use errors.As to branch on the kind, and read the decoded body for a message:

go
import (
	"errors"
	"fmt"
 
	americancloudsdkgo "github.com/American-Cloud/americancloud-sdk-go"
)
 
vm, err := client.Vms.GetVms(ctx, &americancloudsdkgo.GetVmsRequest{ID: "vm-123"})
if err != nil {
	var notFound *americancloudsdkgo.NotFoundError
	if errors.As(err, &notFound) {
		fmt.Println("no such VM:", notFound.Body.GetMessage())
		return
	}
	return err
}

Each typed error embeds the SDK's core.APIError, so its StatusCode field is always available even when you don't need to distinguish the specific kind.

Paginate list endpoints

List calls are page-based. The request struct takes optional Page (1-indexed, defaults to 1) and PageSize (defaults to 100, server cap 500) pointers, and the response carries Total — the count across all pages — alongside the current page's Data. Use the SDK's pointer helpers to set the optional fields:

go
import americancloudsdkgo "github.com/American-Cloud/americancloud-sdk-go"
 
page := 1
for {
	resp, err := client.Vms.ListVms(ctx, &americancloudsdkgo.ListVmsRequest{
		Page:     americancloudsdkgo.Int(page),
		PageSize: americancloudsdkgo.Int(100),
	})
	if err != nil {
		return err
	}
 
	for _, vm := range resp.Data {
		fmt.Printf("%s\t%s\t%s\n", vm.ID, vm.Name, vm.Status)
	}
 
	if float64(page*100) >= resp.Total {
		break
	}
	page++
}

Passing nil as the request fetches the first page with default sizing.

Versioning

The SDK version is the API version: SDK 1.8.0 is generated from API 1.8.0, in lockstep with the TypeScript and Python clients. The 1.x line targets API v1. A major release tracks a new API URL version and can require code changes. Read the changelog before any upgrade. From v1.8.0, the client takes an API token (option.WithToken). Write code that tolerates unknown response fields and new enum values gracefully — additive changes ship within a version. See SDKs overview for the full policy.

Next steps

Contact us