Getting Started with the AlertOps .NET SDK

Overview

Relevant for Developers automating AlertOps from C# or any .NET 8 language

The AlertOps .NET SDK (AlertOps.Sdk) wraps the whole AlertOps REST surface in one client object: the v2 and v3 APIs, alert ingestion, the public status viewer and the AI backends. Each of the 802 endpoints is an …Async method on a resource, such as ao.Groups.ListAsync or ao.EscalationPolicies.CreateAsync. 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 PascalCase plus Async.
Proven, not ported by hand: every request, helper flow, pure function and semantic-layer trace replays Python's recorded wire traffic exactly (dotnet test).
Idiomatic: System.Text.Json (JsonNode results), async/await with a CancellationToken on every call, and an injectable HttpClient.
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 targets .NET 8 and depends only on the base class library. Add it from NuGet:

dotnet add package AlertOps.Sdk

using AlertOps;              // client, resources, Kwargs, errors
using AlertOps.Semantic;     // planners, Report, Blueprint
using System.Text.Json.Nodes;

Configure credentials

Relevant for Developers connecting the SDK to a tenant

The client reads ALERTOPS_* environment variables. Values in a Dotenv file override the environment, so a stale exported key can't shadow the file. Properties set on AlertOpsOptions 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 TimeSpan. Default 30 s.
MaxRetries	ALERTOPS_MAX_RETRIES	Default 3 (see Calling the API from .NET).
Dotenv		Path of a .env file whose values override the environment.
HttpClient		Your own HttpClient, for proxies, handlers or tests. The SDK creates and disposes one when you don't.

using var ao = new AlertOpsClient(new AlertOpsOptions { Dotenv = ".env" });

Keep keys out of client applications
An API key acts as its user on the whole tenant. Use the SDK from servers, scripts and CI, never from code shipped to end users.

Make your first calls

Relevant for Developers trying the SDK for the first time

Every method returns a Task of the parsed JSON response (JsonNode?).

Create the client: using var ao = new AlertOpsClient();.
Read something: var account = await ao.Account.GetAsync();.
List with a filter: var groups = await ao.Groups.ListAsync(new Kwargs { ["search"] = "Network" });.
Use a helper: var (group, created) = await ao.Groups.EnsureAsync("Network Ops");.

using AlertOps;

using var ao = new AlertOpsClient();
var zone = await ao.Account.TimeZoneAsync();                          // "Eastern Standard Time"
var (group, _) = await ao.Groups.EnsureAsync("Network Ops");
await ao.Groups.Members.AddUsersAsync(group!["group_id"]!, new object?[] { 7, 8 });   // Primary role by default

try
{
    await ao.Groups.GetAsync(999999);
}
catch (NotFoundError e)
{
    Console.WriteLine($"no such group {e.Status}: {string.Join("; ", e.Messages)}");
}

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 UpdateBasicAsync).
Paginated variants	…AllAsync(), …IterAsync()	ListAllAsync() collects every page into a JsonArray. ListIterAsync() is an IAsyncEnumerable<JsonNode?>.
Helpers	same resources	Composite calls ported from Python, such as ao.Alerts.ResolveAsync and ao.Inbound.CreateApiAsync.
Semantic layer	ao.Semantic, Planner	Planners that turn intent into payloads, and an executor that applies and verifies them.
Escape hatch	ao.RequestAsync(method, path, options)	Any path the SDK does not model yet.

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

Troubleshooting

Relevant for Anyone whose first call fails

ConfigurationError: No AlertOps API key

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

AuthenticationError (401)

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

ConfigurationError: … base 'ai_chat' has no URL configured

Set AiChatBaseUrl. The AI chat backend has no public default.

Need help?

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