For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/reference/api/sdk-go.md.
  • English
  • How to use the Clickmax Go SDK

    The clickmax.io/go module calls the Clickmax API from Go code. Each endpoint has a typed method, and every failed call returns a *clickmax.Error with the error category.

    Before you start, you need:

    • a workspace API key, created by an owner or admin under Settings > Connections > API (details in Clickmax API authentication);
    • Go 1.24 or later. The module has no dependencies outside the standard library.
    Keep the key on the server

    The key acts on behalf of the whole workspace. Use the SDK only on a server and load the key from an environment variable or a secret manager. Never include the key in code that runs in a browser or a mobile app.

    Make your first call

    Install the module

    go get clickmax.io/go

    Create the client

    The import path is clickmax.io/go and the package name is clickmax:

    import "clickmax.io/go"
    
    c, err := clickmax.New(os.Getenv("CLICKMAX_API_KEY"))
    if err != nil {
    	log.Fatal(err)
    }

    clickmax.New makes no request. It returns an error when the key is empty or malformed or when an option is invalid.

    Call an endpoint

    Methods are grouped by resource and follow the endpoint path: /tags/list becomes c.Tags.List(ctx). Endpoints without a resource are methods of the client itself, such as /whoami, which becomes c.Whoami(ctx).

    Every method takes a context.Context as its first argument. Canceling the context stops the request.

    ctx := context.Background()
    
    tags, err := c.Tags.List(ctx)
    if err != nil {
    	log.Fatal(err)
    }
    for _, tag := range tags.Data {
    	fmt.Println(tag.Name)
    }

    Read endpoints with query parameters take a params struct and write endpoints take the request body as the second argument; clickmax.Ptr builds the pointer an optional field needs.

    created, err := c.Tags.Create(ctx, clickmax.TagsCreateInput{Name: "VIP", Color: clickmax.Ptr("ff8800")})
    if err != nil {
    	log.Fatal(err)
    }
    fmt.Println(created.ID)

    Handle the error

    Use errors.As to read the *clickmax.Error and decide how to handle it by its Type field:

    tags, err := c.Tags.List(ctx)
    if err != nil {
    	var cerr *clickmax.Error
    	if errors.As(err, &cerr) {
    		switch cerr.Type {
    		case clickmax.ErrorTypeAuthentication:
    			log.Printf("key rejected: code=%s request_id=%s", cerr.Code, cerr.RequestID)
    		case clickmax.ErrorTypeRateLimit:
    			log.Printf("request limit reached, retry in %s", cerr.RetryAfter)
    		default:
    			log.Printf("tags.list failed: type=%s code=%s request_id=%s", cerr.Type, cerr.Code, cerr.RequestID)
    		}
    	}
    	return
    }
    for _, tag := range tags.Data {
    	fmt.Println(tag.Name)
    }

    Type and Code take the same values as the type and code fields described in Clickmax API errors. When you contact support, include the RequestID. RetryAfter is the wait time from the Retry-After header, or zero when the header is missing or unreadable.

    When no usable response arrives, the SDK uses its own types: ErrorTypeNetwork, ErrorTypeTimeout, ErrorTypeAborted, and ErrorTypeParse.

    See the options and every method

    The clickmax-go repository README explains optional and null fields, the WithTimeout, WithHeader, and WithHTTPClient options, and how to retry after a rate_limit error. Options apply to the whole client or to a single call. The SDK never retries requests on its own.

    The package documentation on pkg.go.dev lists every method with its input and response types.

    Update the module

    Each module version matches API v0 as it was when the version was published. Because v0 can still change, keep the version you tested in go.mod and test your integration before updating.