SC26AI agents lab + dinner on the river · Nov 17
Parallel Works
View as Markdown
Share:

Go SDK

The official Go client for the ACTIVATE platform API. Requires Go 1.18 or later.

Installation

go get github.com/parallelworks/sdk/go/v7

Quick Start

For CI or another unattended job, supply an API key through PW_API_KEY. The SDK extracts its platform host. For work you run yourself, including long-running scripts, use your saved CLI sign-in instead:

import parallelworks "github.com/parallelworks/sdk/go/v7"
 
client, err := parallelworks.NewClientFromCredential(os.Getenv("PW_API_KEY"))
if err != nil {
    log.Fatal(err)
}
 
workflows, err := client.ListWorkflows(context.Background())

Authentication

Signed in with pw auth

For scripts you run yourself, sign in with pw auth, then create the client from CLI credential config. The SDK automatically obtains OAuth access tokens, authenticates requests, and renews tokens through the CLI while your sign-in remains valid. Your code does not need to manage tokens or refresh logic. The SDK runs pw auth token --print -o json when it needs a token, so keep the CLI installed and on your PATH.

client, err := parallelworks.NewClientFromCredentialConfig()
if err != nil {
    log.Fatal(err)
}
 
workflows, err := client.ListWorkflows(context.Background())

The client uses the same context as the CLI: PW_API_KEY if set, then WithContext, PW_CONTEXT, and the current context. WithCLICommand sets the path to pw. If pw can't renew the sign-in, requests fail with ErrSignInExpired; run pw auth again.

To select a context named research, use parallelworks.NewClientFromCredentialConfig(parallelworks.WithContext("research")). Without an explicit context, the client uses PW_CONTEXT or the saved default. A nonempty PW_API_KEY overrides even the explicitly named context, so unset it to use your saved sign-in.

For long-running work, reuse this client instead of passing a copied access token to a raw-credential constructor. PW_CREDENTIALS_DIR selects a separate $PW_CREDENTIALS_DIR/.credentials file for both the SDK and its CLI subprocess. Set it before creating the client and keep the directory writable. See long-running clients and separate credentials.

For CI and persistent unattended services, use an API key in PW_API_KEY and follow the key rotation steps.

Automatic Host Detection

These raw-credential constructors infer the host, but do not renew the credential you pass. Use the credential-config constructor above for a renewable sign-in.

An API key (pwt_...) contains your platform host, so NewClientFromCredential connects to it with no URL. An access token from pw auth token --print doesn't name a host: the client uses PW_PLATFORM_HOST if set, otherwise the server of the selected CLI context.

// API key: host decoded from the key
client, _ := parallelworks.NewClientFromCredential("pwt_Y2xvdWQucGFyYWxsZWwud29ya3M.xxxxx")
// Connects to: https://cloud.parallel.works
 
// Access token from `pw auth token --print`: host from PW_PLATFORM_HOST,
// else the server of the selected context
client, _ := parallelworks.NewClientFromCredential(token)

Explicit Host

If you prefer to specify the host explicitly:

// API key (Basic Auth) - for CI and other unattended automation
client := parallelworks.NewClient(
    "https://cloud.parallel.works",
    parallelworks.WithAuth(&parallelworks.BasicAuth{
        Username: "pwt_...",
    }),
)
 
// Access token (Bearer), sent as is and never renewed
client := parallelworks.NewClient(
    "https://cloud.parallel.works",
    parallelworks.WithAuth(&parallelworks.BearerAuth{
        Token: token,
    }),
)

Credential Helpers

parallelworks.IsAPIKey("pwt_abc.xyz")         // true
parallelworks.IsToken("eyJ.abc.def")          // true
parallelworks.ExtractPlatformHost("pwt_...")  // "cloud.parallel.works", nil

Client Options

client := parallelworks.NewClient(
    "https://cloud.parallel.works",
    parallelworks.WithAuth(&parallelworks.BasicAuth{Username: "pwt_..."}),
    parallelworks.WithHTTPClient(customHTTPClient),
    parallelworks.WithUserAgent("my-app/1.0"),
    parallelworks.WithDefaultRetry(),
    parallelworks.WithMiddleware(loggingMiddleware),
)

Retry

Enable automatic retries with exponential backoff:

// Use default retry config (3 retries, retries on 429/5xx)
client := parallelworks.NewClient(url, parallelworks.WithDefaultRetry())
 
// Or customize
client := parallelworks.NewClient(url, parallelworks.WithRetry(parallelworks.RetryConfig{
    MaxRetries:           5,
    BaseDelay:            2 * time.Second,
    MaxDelay:             60 * time.Second,
    Multiplier:           2.0,
    RetryableStatusCodes: []int{429, 500, 502, 503, 504},
}))

Middleware

Add custom middleware to intercept requests:

logging := func(req *http.Request, next parallelworks.RoundTripFunc) (*http.Response, error) {
    log.Printf("%s %s", req.Method, req.URL)
    return next(req)
}
 
client := parallelworks.NewClient(url, parallelworks.WithMiddleware(logging))

Error Handling

API errors can be matched with sentinel errors using errors.Is:

_, err := client.ListWorkflows(ctx)
if errors.Is(err, parallelworks.ErrNotFound) {
    // handle 404
} else if errors.Is(err, parallelworks.ErrUnauthorized) {
    // handle 401
}

Related Documentation