Getting Started with the AlertOps TypeScript SDK

Overview

Relevant for Developers automating AlertOps from Node.js or TypeScript

The AlertOps TypeScript 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 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 camelCase.
Proven, not ported by hand: every request, helper flow and pure function replays Python's recorded wire traffic byte for byte (npm test).
Zero runtime dependencies: built-in fetch, ESM and CommonJS builds, Node 18+.
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 Node 18 or later and has no runtime dependencies. Install it from npm:

npm install @alertops/sdk

Both module systems work:

import { AlertOps } from "@alertops/sdk";          // ESM
const { AlertOps } = require("@alertops/sdk");      // CommonJS

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. Options passed to the constructor 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.
timeoutMs	ALERTOPS_TIMEOUT (seconds)	Per request. Default 30000 ms.
maxRetries	ALERTOPS_MAX_RETRIES	Default 3 (see Calling the API from TypeScript).
dotenv		Path of a .env file whose values override the environment.
fetch		Your own fetch, for proxies or tests.

const ao = new AlertOps({ dotenv: ".env" });

Keep keys out of front-end code
An API key acts as its user on the whole tenant. Use the SDK from servers, scripts and CI, never from a browser bundle.

Make your first calls

Relevant for Developers trying the SDK for the first time

Every method returns a promise of the parsed JSON response.

Create the client: const ao = new AlertOps();.
Read something: const account = await ao.account.get();.
List with a filter: const groups = await ao.groups.list({ search: "Network" });.
Use a helper: const [group, created] = await ao.groups.ensure("Network Ops");.

import { AlertOps, NotFoundError } from "@alertops/sdk";

const ao = new AlertOps();
const zone = await ao.account.timeZone();                 // "Eastern Standard Time"
const [group] = await ao.groups.ensure("Network Ops");
await ao.groups.members.addUsers(group.group_id, [7, 8]); // Primary role by default

try {
  await ao.groups.get(999999);
} catch (e) {
  if (e instanceof NotFoundError) console.log("no such group", e.status, 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 updateBasic).
Paginated variants	…All(), …Iter()	listAll() collects every page. listIter() is an async iterator.
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(method, path, options)	Any path the SDK does not model yet.

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

Troubleshooting

Relevant for Anyone whose first call fails

ConfigurationError: No AlertOps API key

Check that ALERTOPS_API_KEY is set in this process, or pass 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.