Login

Go SDK quickstart

Last updated: June 5, 2026

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 needs both parts of an API key pair. Create and manage keys at console.americancloud.com/api-keys. The client secret is shown once at creation — store it securely (an environment variable or secrets manager, never your repo). If it's lost, revoke the key and create a new one.

Keys are scoped at creation. A read-only key can call GET endpoints only; a read-write key has full access to resource management. Start with a read-only key and upgrade when you're ready to create resources.

Pass the pair to the client through option.WithAPIKey (the client ID) and option.WithAPIClientSecret. Reading them from the environment keeps secrets out of source:

sh
export AMERICANCLOUD_API_CLIENT_ID="your-client-id"
export AMERICANCLOUD_API_CLIENT_SECRET="your-client-secret"

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 key 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.WithAPIKey(os.Getenv("AMERICANCLOUD_API_CLIENT_ID")),
		option.WithAPIClientSecret(os.Getenv("AMERICANCLOUD_API_CLIENT_SECRET")),
	)
 
	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. This is a read-write program — the create step needs a read-write key.

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.WithAPIKey(os.Getenv("AMERICANCLOUD_API_CLIENT_ID")),
		option.WithAPIClientSecret(os.Getenv("AMERICANCLOUD_API_CLIENT_SECRET")),
	)
 
	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.3.0 is generated from API 1.3.0, in lockstep with the TypeScript and Python clients. The 1.x line targets API v1. Patch and minor releases are backward-compatible and safe to upgrade; a major release tracks a new API URL version and is the only release that can require code changes. 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