Portainer Client GO SDK

Swagger-generated client SDK in Golang for the Portainer Business Edition API.

Installation

Use the following command to install the latest version of the SDK:

go get -u github.com/portainer/client-api-go/v2

To install a specific version of the SDK (to target a specific Portainer server version):

go get -u github.com/portainer/client-api-go/v2@VERSION

For example, to install version 2.31.2:

go get -u github.com/portainer/client-api-go/v2@v2.31.2

Available versions can be found at: https://github.com/portainer/client-api-go/tags

Versioning

Each SDK tag matches the Portainer server version it targets. Installing v2.31.2 of the SDK gives you a client generated from the Portainer 2.31.2 swagger spec.

The /v2 in the module path is a Go Semantic Import Versioning requirement, not a marker of "SDK API v2".

Using the Client SDK

There are two ways to use the SDK:

1. Using the Simple Client (Recommended)

The simple client provides an easy-to-use interface to interact with the Portainer API. All the Portainer API operations are not supported yet.

import client "github.com/portainer/client-api-go/v2/client"

// Initialize client with API key
cli := client.NewPortainerClient(
	"portainer.dev.local",   // Portainer host
	"ptr_XXXYYYZZZ",         // Portainer API key
	client.WithSkipTLSVerify(true),  // Optional: disables TLS certificate verification (default: false)
	client.WithScheme("https"),      // Optional: defaults to "https"
	client.WithBasePath("/api"),     // Optional: defaults to "/api"
)

// List all environments
endpoints, err := cli.ListEndpoints()
if err != nil {
	log.Fatalf("Failed to list Portainer environments: %v", err)
}

// Process endpoints as needed...

See the example/simple/client.go file for a complete example using the simple client.

2. Using the Swagger-Generated Client (Advanced)

The simple client is still a work in progress; if you need to access API operations that aren't yet supported by the simple client, you can use the underlying Swagger-generated client directly.

import (
	"github.com/go-openapi/runtime"
	client "github.com/portainer/client-api-go/v2/pkg/client"
	"github.com/portainer/client-api-go/v2/pkg/client/endpoints"
)

// Create transport
transport := httptransport.New(
	"portainer.dev.local",
	"/api",
	[]string{"https"},
)

// Create client instance
portainerClient := client.New(transport, strfmt.Default)

// Set up API key authentication
apiKeyAuth := runtime.ClientAuthInfoWriterFunc(func(r runtime.ClientRequest, _ strfmt.Registry) error {
	return r.SetHeaderParam("x-api-key", "ptr_XXXYYYZZZ")
})
transport.DefaultAuthentication = apiKeyAuth

// List all environments
endpointsParams := endpoints.NewEndpointListParams()
endpointsResp, err := portainerClient.Endpoints.EndpointList(endpointsParams, nil)
if err != nil {
	log.Fatalf("Failed to list Portainer environments: %v", err)
}

// Process endpoints as needed...

See the example/swagger/client.go file for a complete example using the Swagger-generated client directly.

Development

To use the latest version of the Portainer API, you must regenerate the underlying API client using Swagger.

The Swagger CLI version is pinned in tools/go.mod and invoked transparently by the Makefile — there is no need to install it manually. The pinned version is downloaded on first use and cached by the Go build cache for subsequent runs.

Generate the client (adjust the VERSION parameter as needed):

make generate-client VERSION=2.31.2

To bump the pinned Swagger CLI version, run go get github.com/go-swagger/go-swagger/cmd/swagger@vX.Y.Z from inside tools/ and commit the resulting tools/go.mod and tools/go.sum.