Introducing the DNScale Go SDK

The official DNScale Go SDK brings DNS operations into Go applications. Use typed requests to manage zones and records, traverse paginated results with for range, and pass a context through each operation to control cancellation and deadlines.

The SDK supports Go 1.25 and newer. Its module path is github.com/dnscaleou/dnscale-go, with source in the DNScale Go SDK repository.

DNS operations where your application needs them

A tenant-onboarding service might create a verification TXT record. A command-line tool might inventory zones before a migration. A background worker might provision DNS for a temporary environment and remove its records when the environment expires.

These workflows already work through the DNScale REST API. The Go SDK supplies a shared client for authentication, typed models, pagination, timeouts, and API errors, so your application can concentrate on when a DNS change should happen.

The SDK uses the same API keys, permissions, and account limits as the REST API. There is no separate SDK account to configure.

Start with a read-only request

From a Go module, install the client:

go get github.com/dnscaleou/dnscale-go

Create an API key with zones:read permission and supply it through the DNSCALE_API_KEY environment variable. See the authentication documentation for scopes and zone restrictions.

Save this example as main.go and run it with go run .:

package main
 
import (
	"context"
	"fmt"
	"log"
	"time"
 
	dnscale "github.com/dnscaleou/dnscale-go"
)
 
func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}
 
func run() error {
	dns, err := dnscale.New(dnscale.Options{})
	if err != nil {
		return err
	}
	defer dns.Close()
 
	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()
 
	for zone, err := range dns.Zones.Iter(ctx, 100) {
		if err != nil {
			return err
		}
		fmt.Println(zone.Id, zone.Name)
	}
	return nil
}

dnscale.New reads the key from the environment. The iterator fetches pages as you consume them, and Close releases idle HTTP connections when the function returns. Breaking out of the loop stops further page requests.

The one-minute context limits the whole listing. Individual requests also have the SDK's default ten-second timeout, including any retry waits.

Typed changes, with explicit outcomes

Zone and record helpers provide List, Iter, Get, Create, Update, and Delete. Request models make the data being sent visible in your code; dnscale.Ptr supplies optional values such as a record's TTL.

The Go SDK guide walks through creating a test zone and a complete TXT record lifecycle. It also explains an important API detail: record IDs are content-derived, so an update can return a different ID. Keep the returned ID for later reads or deletion.

Errors and retries your application can control

The SDK exposes APIError and RateLimitError for inspection with Go's errors.As. HTTP status, API error code, message, and request ID are available when supplied by the API. Network failures remain ordinary Go errors.

Safe read requests can retry transient failures, with up to two retries by default. Create, update, and delete operations are never automatically retried. If a write times out, read the current state before deciding whether to repeat it.

Pass an existing request context from your service, or create a deadline for a batch job. Cancellation also interrupts retry waits. Configure Options.Timeout and Options.MaxRetries when a workflow needs a different request budget.

Access the wider API

The convenience layer covers zones and records. dns.API exposes the generated client for the rest of the public OpenAPI contract, including DNSSEC, usage, billing, and account operations. Generated requests sent through dns.API share the SDK's authentication, timeout, retry, and error handling.

Models for those operations live in github.com/dnscaleou/dnscale-go/api. The bundled contract and generated code travel with the module; applications do not need to run a generator.

Choose the integration that fits your workflow

Use the Go SDK when DNS operations belong inside a Go service or tool. The Python SDK serves Python applications, while Terraform and DNSControl fit workflows that manage DNS as declared configuration.

The SDK does not maintain desired state, generate an apply plan, or reconcile drift. Give each record set a clear owner so application code and infrastructure tooling do not routinely overwrite the same records.

Start with the Go SDK guide, explore the SDKs learning section, or consult the zone and record references for endpoint details.