Getting Started with the AlertOps Go SDK

Overview

Relevant for Developers automating AlertOps from Go

The AlertOps Go SDK (github.com/alertops/alertops-go, package alertops) wraps the whole AlertOps REST surface in one client: the v2 and v3 APIs, alert ingestion, the public status viewer and the AI backends. Each of the 802 endpoints is a method on a resource, such as ao.Groups.List or ao.EscalationPolicies.Create. The endpoint layer is generated from the spec that the Python reference SDK exports, and its behaviour is proven against vectors recorded from Python.

Key benefits:

Complete: every endpoint the Python SDK covers, with the same names in Go style (update_basic becomes UpdateBasic).
Proven, not ported by hand: every request, helper flow and pure function replays Python's recorded wire traffic byte for byte (go test ./...).
Standard library only: net/http, context.Context first on every call, Go 1.23+ iterators for pagination.
Helpers included: find-or-create, read-merge-write, alert ingestion, and the semantic planners and executor.

Installation

Relevant for Developers setting up a project

The SDK needs Go 1.23 or later and has no dependencies outside the standard library. Add it to your module:

go get github.com/alertops/alertops-go

import alertops "github.com/alertops/alertops-go"

Configure credentials

Relevant for Developers connecting the SDK to a tenant

alertops.New reads the ALERTOPS_* environment variables. Values in the Dotenv file override the environment, so a stale exported key can't shadow the file. Fields set on Options win over both.

Option	Environment variable	Description
APIKey	ALERTOPS_API_KEY	The API key. Sent as api-key on v2 and x-api-key on v3.
SessionToken	ALERTOPS_SESSION_TOKEN	UI session token, only for the few login-only endpoints.
V2BaseURL / V3BaseURL	ALERTOPS_V2_BASE_URL / ALERTOPS_V3_BASE_URL	Default https://app.alertops.com/api/v2 and /api/v3.
NotifyBaseURL	ALERTOPS_NOTIFY_BASE_URL	Alert ingestion host, default https://notify.alertops.com.
AIChatBaseURL	ALERTOPS_AI_CHAT_BASE_URL	No public default. Set it to use ao.AIChat.
Timeout	ALERTOPS_TIMEOUT (seconds)	Per request, a time.Duration. Default 30 s.
MaxRetries	ALERTOPS_MAX_RETRIES	Default 3. Use alertops.Ptr(0) for none (see Calling the API from Go).
Dotenv		Path of a .env file whose values override the environment.
HTTPClient		Your own *http.Client (or any Doer), for proxies or tests.

ao := alertops.New(alertops.Options{Dotenv: ".env"})

Keep keys out of shared code
An API key acts as its user on the whole tenant. Load it from the environment or a .env file that is never committed, and use the SDK from servers, scripts and CI.

Make your first calls

Relevant for Developers trying the SDK for the first time

Every method takes a context.Context first and returns the parsed JSON response and an error.

Create the client: ao := alertops.New(alertops.Options{}).
Read something: account, err := ao.Account.Get(ctx, nil).
List with a filter: groups, err := ao.Groups.List(ctx, &alertops.Request{Fields: alertops.M{"search": "Network"}}).
Use a helper: group, created, err := ao.Groups.Ensure(ctx, "Network Ops", nil).

ctx := context.Background()
ao := alertops.New(alertops.Options{})
zone, _ := ao.Account.TimeZone(ctx)                    // "Eastern Standard Time"
group, _, err := ao.Groups.Ensure(ctx, "Network Ops", nil)
if err != nil {
	log.Fatal(err)
}
_, err = ao.Groups.Members.AddUsers(ctx, alertops.Get(group, "group_id"), []any{7, 8}, nil) // Primary by default

_, err = ao.Groups.Get(ctx, 999999, nil)
var nf *alertops.NotFoundError
if errors.As(err, &nf) {
	fmt.Println("no such group", nf.Status, nf.Messages, zone)
}

How the SDK is organised

Relevant for Developers finding the method they need

Part	Where	What it holds
Resources	ao.<Resource>.<Sub>…	One generated method per endpoint, named after the Python op (update_basic becomes UpdateBasic).
Paginated variants	…All, …Iter	ListAll collects every page. ListIter returns an iter.Seq2[any, error] for for … range.
Helpers	same resources	Composite calls ported from Python, such as ao.Alerts.Resolve and ao.Inbound.CreateAPI.
Semantic layer	ao.Semantic, PlanRotation, PlanEscalation	Planners that turn intent into payloads, and an executor that applies and verifies them.
Escape hatch	ao.Request(ctx, method, path, opts)	Any path the SDK does not model yet.

Each method's doc comment (go doc) shows its HTTP line (GET {v2}/groups/{group_id}) and any flags, such as destructive, billing or side effect. docs/REFERENCE.md lists them all.

Troubleshooting

Relevant for Anyone whose first call fails

No AlertOps API key: pass Options.APIKey or set ALERTOPS_API_KEY

Check that ALERTOPS_API_KEY is set in this process, or set Options.APIKey or Options.Dotenv.

AuthenticationError (401)

Check that the key is current. A regenerated key invalidates the old one.

base 'ai_chat' has no URL configured

Set Options.AIChatBaseURL. The AI chat backend has no public default.

Need help?

Email support@alertops.com or contact your AlertOps representative.