Use the Nuon API from Go

The Nuon Go SDK provides typed access to the Nuon control-plane API. Use it to work with organizations, apps, installs, components, workflows, action workflows, runbooks, and other Nuon resources from a Go program.

Package to use: github.com/nuonco/nuon/sdks/nuon-go The former standalone package at github.com/nuonco/nuon-go is deprecated. New integrations should use the SDK in the main Nuon repository.

Requirements

Go 1.24.4 or later
A Nuon API token
The ID of the Nuon organization the request should access

The examples use these environment variables:

Variable	Required	Description
`NUON_API_TOKEN`	Yes	Bearer token used to authenticate API requests.
`NUON_ORG_ID`	Yes for organization-scoped operations	Nuon organization ID sent with each request.
`NUON_API_URL`	No for Nuon Cloud; required in practice for BYOC	API base URL. The examples default to `https://api.nuon.co`, but BYOC clients must target their deployed control plane.
`NUON_INSTALL_ID`	Yes for the example lookup	ID of the install to retrieve.

The SDK does not read environment variables itself. Your program must read them and pass their values to the client constructor.

Match the SDK to the deployed control plane

Version selection is part of correctness for BYOC integrations. The SDK’s methods, request types, response types, enum values, and validation are generated from a particular snapshot of the Nuon control-plane OpenAPI document. A BYOC control plane may run a different Nuon release from Nuon Cloud, especially during a rollout. Do not assume that the latest SDK is compatible with every deployed control plane. Nuon does not currently publish a broad SDK/API compatibility matrix, and the SDK does not perform a runtime compatibility handshake. Before selecting or upgrading the SDK:

Query the control plane the integration will actually call:
curl -fsS "${NUON_API_URL%/}/version"
A response includes the deployed version, source git_ref, and recommended_cli_version. For example, Nuon Cloud at https://api.nuon.co returned the following on August 10, 2026:
{ "git_ref": "0.19.1113", "recommended_cli_version": "0.19.1102", "version": "0.19.1113" }
This example is a point-in-time response, not a version recommendation. Query the target control plane before selecting or upgrading its SDK.
Pin the SDK version or source revision verified for that control-plane release. Do not infer compatibility from version-number similarity: control-plane and SDK module versions are separate release streams.
Test the exact SDK and control-plane pairing in a non-production environment. Exercise every endpoint and model shape the integration uses, including pagination and writes.
Record the verified pairing in the integration’s release metadata or dependency-update notes.

For example, pin a published SDK module release rather than asking Go for latest:

go get github.com/nuonco/nuon/sdks/nuon-go@<verified-sdk-version>

If Nuon identifies a source revision rather than a published SDK module version, Go can pin the module from that revision and record a pseudo-version in go.mod:

go get github.com/nuonco/nuon/sdks/nuon-go@<verified-git-ref>

Commit both go.mod and go.sum. Avoid an unreviewed go get ...@latest in automated dependency updates.

Plan control-plane and client upgrades together

Treat a control-plane upgrade and an SDK upgrade as one compatibility change, even when they are deployed separately:

Inventory the SDK methods and generated model fields the integration uses.
Validate the existing client against the candidate control plane.
Validate the candidate SDK against the candidate control plane.
If the candidate control plane remains compatible with the existing client, upgrade the control plane first, then the client. This avoids deploying a client that calls endpoints an older control plane does not have.
If either side contains a breaking API change, coordinate the rollout and get an explicit supported upgrade path from Nuon rather than relying on deployment order alone.
Keep rollback artifacts for both the client and control plane until production verification is complete.

recommended_cli_version applies to the Nuon CLI; it is useful release context but is not an SDK compatibility declaration. Likewise, API responses include X-Nuon-API-Version, but the Go SDK does not currently read or enforce that header. These values are useful for diagnostics and deployment checks, not proof of compatibility.

Install the SDK

go get github.com/nuonco/nuon/sdks/nuon-go@<verified-sdk-version>

Import the client and, when needed, its generated model types:

import (
	nuon "github.com/nuonco/nuon/sdks/nuon-go"
	"github.com/nuonco/nuon/sdks/nuon-go/models"
)

Create a client

Create one client and reuse it. WithURL is required. In most integrations, validate the token and organization ID before constructing the client so configuration errors fail early.

package main

import (
	"context"
	"fmt"
	"os"
	"strings"
	"time"

	nuon "github.com/nuonco/nuon/sdks/nuon-go"
)

func main() {
	apiURL := strings.TrimSpace(os.Getenv("NUON_API_URL"))
	if apiURL == "" {
		apiURL = "https://api.nuon.co"
	}

	token := strings.TrimSpace(os.Getenv("NUON_API_TOKEN"))
	if token == "" {
		panic("NUON_API_TOKEN is required")
	}

	orgID := strings.TrimSpace(os.Getenv("NUON_ORG_ID"))
	if orgID == "" {
		panic("NUON_ORG_ID is required")
	}

	installID := strings.TrimSpace(os.Getenv("NUON_INSTALL_ID"))
	if installID == "" {
		panic("NUON_INSTALL_ID is required")
	}

	client, err := nuon.New(
		nuon.WithURL(apiURL),
		nuon.WithAuthToken(token),
		nuon.WithOrgID(orgID),
	)
	if err != nil {
		panic(fmt.Errorf("create Nuon API client: %w", err))
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	install, err := client.GetInstall(ctx, installID)
	if err != nil {
		panic(fmt.Errorf("get install: %w", err))
	}

	fmt.Printf("%s: %s\n", install.ID, install.Name)
}

The Cloud default is an application choice in this example, not an SDK default. nuon.New requires WithURL; it does not automatically select Nuon Cloud or discover a BYOC control plane. For software that must never fall back from BYOC to Nuon Cloud, require NUON_API_URL instead of applying the default:

apiURL := strings.TrimSpace(os.Getenv("NUON_API_URL"))
if apiURL == "" {
	panic("NUON_API_URL is required")
}

The client sends the following headers automatically:

Authorization: Bearer <NUON_API_TOKEN>
X-Nuon-Org-ID: <NUON_ORG_ID>

Do not log tokens, include them in error messages, or commit them to source control.

Switch organizations

Organization-scoped methods use the client’s current organization ID. If an application intentionally operates across organizations, update it before the next request:

client.SetOrgID(orgID)

Avoid changing the organization concurrently on a client shared by multiple goroutines. Prefer one client per organization in concurrent multi-organization applications.

Call the API

The SDK exposes a nuon.Client interface with resource-oriented methods. Most methods accept a context.Context, identifiers, and an optional generated request or query model.

Get one resource

install, err := client.GetInstall(ctx, installID)
if err != nil {
	return fmt.Errorf("get install %q: %w", installID, err)
}

Other common lookups follow the same pattern:

app, err := client.GetApp(ctx, appID)
component, err := client.GetInstallComponent(ctx, installID, componentID)
workflow, err := client.GetWorkflow(ctx, workflowID)
stack, err := client.GetInstallStack(ctx, installID)

Create or update a resource

Request and response types live in the models package:

req := &models.ServiceUpdateInstallRequest{
	Name: "production-us-east-1",
}

install, err := client.UpdateInstall(ctx, installID, req)
if err != nil {
	return fmt.Errorf("update install %q: %w", installID, err)
}

The model types are generated from Nuon’s OpenAPI definition. Consult the SDK models for the fields accepted by a particular request.

Work with nested data

Some resources support recursive responses. For example, requesting an app configuration with recurse enabled includes its related configuration data:

recurse := true
config, err := client.GetAppConfig(ctx, appID, appConfigID, &recurse)
if err != nil {
	return fmt.Errorf("get app config %q: %w", appConfigID, err)
}

Paginate every list operation

Paginated methods return three values:

(items, hasMore, error)

Passing nil as the query uses the server default, which is currently 10 results. If the integration needs the complete collection, continue until hasMore is false.

func allInstallComponents(
	ctx context.Context,
	client nuon.Client,
	installID string,
) ([]*models.AppInstallComponent, error) {
	const pageSize = 100

	var all []*models.AppInstallComponent
	for offset := 0; ; offset += pageSize {
		page, hasMore, err := client.GetInstallComponents(
			ctx,
			installID,
			&models.GetPaginatedQuery{
				Offset: offset,
				Limit:  pageSize,
			},
		)
		if err != nil {
			return nil, fmt.Errorf(
				"list install components at offset %d: %w",
				offset,
				err,
			)
		}

		all = append(all, page...)
		if !hasMore {
			return all, nil
		}
	}
}

The same pattern applies to methods such as GetApps, GetAllInstalls, GetAppInstalls, GetAppComponents, GetWorkflows, and GetInstallDeploys. The maximum page size is 100. Do not increment the offset by the number of returned records; increment it by the requested page size, as shown above.

Handle errors

Always preserve the SDK error with %w when adding operation-specific context:

install, err := client.GetInstall(ctx, installID)
if err != nil {
	return fmt.Errorf("get install %q: %w", installID, err)
}

The SDK includes helpers for common HTTP error classes:

nuon.IsBadRequest(err) — HTTP 400
nuon.IsUnauthorized(err) — HTTP 401
nuon.IsForbidden(err) — HTTP 403
nuon.IsNotFound(err) — HTTP 404
nuon.IsServerError(err) — HTTP 5xx
nuon.ToAPIError(err) — extracts a readable API error message
nuon.ToUserError(err) — extracts an API response explicitly marked as a user error

Classify an error before wrapping it. The status helpers currently inspect the direct SDK error, while ToAPIError and ToUserError walk wrapped error chains.

install, err := client.GetInstall(ctx, installID)
if err != nil {
	switch {
	case nuon.IsUnauthorized(err):
		return fmt.Errorf("Nuon API token was rejected: %w", err)
	case nuon.IsForbidden(err):
		return fmt.Errorf("token cannot access organization %q: %w", orgID, err)
	case nuon.IsNotFound(err):
		return fmt.Errorf("install %q does not exist: %w", installID, err)
	case nuon.IsServerError(err):
		return fmt.Errorf("Nuon API server error: %w", err)
	default:
		return fmt.Errorf("get install %q: %w", installID, err)
	}
}

Respect context cancellation and timeouts separately when callers need to distinguish them:

if err != nil {
	if errors.Is(err, context.DeadlineExceeded) {
		return fmt.Errorf("Nuon API request timed out: %w", err)
	}
	return fmt.Errorf("get install %q: %w", installID, err)
}

Common API areas

The public client covers these major resource groups:

Area	Representative methods
Authentication and organizations	`ValidateToken`, `GetAuthMe`, `GetOrg`, `GetOrgs`, `SetOrgID`
Apps and app configuration	`GetApps`, `GetApp`, `CreateApp`, `GetAppConfig`, `GetAppLatestConfig`, `BuildAppConfig`
Components and builds	`GetAppComponents`, `GetComponent`, `GetComponentBuilds`, `GetComponentLatestBuild`
Installs	`GetAllInstalls`, `GetInstall`, `CreateInstall`, `UpdateInstall`, `ReprovisionInstall`, `DeprovisionInstall`
Install components and deploys	`GetInstallComponents`, `GetInstallDeploys`, `DeployInstallComponents`, `GetInstallComponentOutputs`
Inputs and secrets	`GetInstallInputs`, `UpdateInstallInputs`, `GetAppSecrets`, `CreateAppSecret`
Workflows	`GetWorkflows`, `GetWorkflow`, `GetWorkflowSteps`, `CancelWorkflow`, `RetryWorkflowStep`
Actions and runbooks	`GetActionWorkflows`, `CreateInstallActionWorkflowRun`, `GetInstallRunbooks`, `CreateInstallRunbookRun`
Runners and logs	`GetInstallRunnerGroup`, `GetRunnerJobs`, `GetLogStream`, `LogStreamTailLogs`
VCS and service accounts	`GetVCSConnections`, `CreateVCSConnection`, `ListServiceAccounts`, `CreateServiceAccountToken`

See the current Client interface for the complete method list and signatures.

Structure integrations for testing

nuon.Client intentionally exposes the whole SDK, which is often more than one package needs. Define a small local interface containing only the methods your code calls. Production code can receive the real SDK client, and tests can provide a focused fake.

type installReader interface {
	GetInstall(context.Context, string) (*models.AppInstall, error)
	GetInstallComponents(
		context.Context,
		string,
		*models.GetPaginatedQuery,
		...nuon.GetInstallComponentsOpts,
	) ([]*models.AppInstallComponent, bool, error)
}

type Service struct {
	api installReader
}

func NewService(api installReader) *Service {
	return &Service{api: api}
}

This keeps test doubles small and prevents application code from depending on generated transport internals.

Recommended integration practices

Use the in-tree SDK path, not the deprecated standalone module.
Identify the deployed control-plane version and git_ref, then pin a verified SDK version for that environment.
Require the correct NUON_API_URL for BYOC integrations; do not silently send their traffic to Nuon Cloud.
Validate NUON_API_TOKEN and NUON_ORG_ID in your configuration layer.
Reuse a client rather than constructing one for every request.
Give network operations a caller-controlled context and timeout.
Paginate list calls explicitly when completeness matters.
Wrap errors with %w, but run the SDK’s HTTP status helpers before wrapping.
Program against the handwritten nuon.Client facade, not generated client/operations transport types.
Treat generated models as versioned API contracts and test them when either the SDK or control plane changes.
Commit the pinned dependency in go.mod and go.sum; avoid unattended @latest upgrades.
Never expose API tokens in logs, command output, or error messages.

Working examples

Two Nuon extensions demonstrate current SDK usage:

nuon-ext-terraform shows client construction, install and app-config lookups, generated model inspection, and complete pagination.
nuon-ext-cf-stack shows client construction and retrieving an install and its stack before operating on AWS resources.

Cloud Reference

Interface Reference

Architecture Reference

Go SDK

Use the Nuon API from Go

Requirements

Match the SDK to the deployed control plane

Plan control-plane and client upgrades together

Install the SDK

Create a client

Switch organizations

Call the API

Get one resource

Create or update a resource

Work with nested data

Paginate every list operation

Handle errors

Common API areas

Structure integrations for testing

Recommended integration practices

Working examples

Reference

​Use the Nuon API from Go

​Requirements

​Match the SDK to the deployed control plane

​Plan control-plane and client upgrades together

​Install the SDK

​Create a client

​Switch organizations

​Call the API

​Get one resource

​Create or update a resource

​Work with nested data

​Paginate every list operation

​Handle errors

​Common API areas

​Structure integrations for testing

​Recommended integration practices

​Working examples

​Reference

Use the Nuon API from Go

Requirements

Match the SDK to the deployed control plane

Plan control-plane and client upgrades together

Install the SDK

Create a client

Switch organizations

Call the API

Get one resource

Create or update a resource

Work with nested data

Paginate every list operation

Handle errors

Common API areas

Structure integrations for testing

Recommended integration practices

Working examples

Reference