Getting Started with the AlertOps Java SDK

Overview

Relevant for Developers automating AlertOps from Java

The AlertOps Java SDK (com.alertops:alertops-sdk) 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 camelCase.
Proven, not ported by hand: every request, helper flow, semantic flow and pure function replays Python's recorded wire traffic byte for byte (./mvnw test).
Small footprint: Java 17+, java.net.http, and Jackson as the only runtime dependency.
Helpers included: find-or-create, read-merge-write, alert ingestion, and the semantic planners and executor.
Thread-safe: one client can be shared by every thread.

Installation

Relevant for Developers setting up a project

The SDK needs Java 17 or later. Its only runtime dependency is Jackson. Add it from Maven Central:

<dependency>
  <groupId>com.alertops</groupId>
  <artifactId>alertops-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

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. Builder settings win over both.

Builder method	Environment variable	Description
apiKey(String)	ALERTOPS_API_KEY	The API key. Sent as api-key on v2 and x-api-key on v3.
sessionToken(String)	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(Duration)	ALERTOPS_TIMEOUT (seconds)	Per request. Default 30 seconds.
maxRetries(int)	ALERTOPS_MAX_RETRIES	Default 3 (see Calling the API from Java).
dotenv(Path)		A .env file whose values override the environment.
httpClient(HttpClient) / transport(Transport)		Your own HttpClient, or a custom transport for proxies, tracing or tests.

AlertOps ao = AlertOps.builder().dotenv(Path.of(".env")).build();

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

Make your first calls

Relevant for Developers trying the SDK for the first time

Every method returns the parsed JSON response as a Jackson JsonNode.

Build the client: AlertOps ao = AlertOps.builder().build();.
Read something: JsonNode account = ao.account().get();.
List with a filter: JsonNode groups = ao.groups().list(Request.of("search", "Network"));.
Use a helper: Shared.Ensured g = ao.groups().ensure("Network Ops");.

import com.alertops.sdk.*;
import com.alertops.sdk.helpers.Shared;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.List;

AlertOps ao = AlertOps.builder().build();
JsonNode zone = ao.account().timeZone();                               // "Eastern Standard Time"
Shared.Ensured g = ao.groups().ensure("Network Ops");
ao.groups().members().addUsers(g.record().get("group_id"), List.of(7, 8));  // Primary role by default

try {
  ao.groups().get(999999);
} catch (NotFoundError e) {
  System.out.println("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). Classes are in com.alertops.sdk.generated, with sub-resources nested (Groups.Members).
Paginated variants	…All(), …Iter()	listAll() collects every page into an AOList. listIter() is a lazy Iterable.
Helpers	same resources	Composite calls ported from Python, such as ao.alerts().resolve(...) and ao.inbound().createApi(...). Implemented in com.alertops.sdk.helpers.
Semantic layer	ao.semantic(), Plan.planRotation, Plan.planEscalation	Planners that turn intent into payloads (com.alertops.sdk.semantic), and an executor that applies and verifies them.
Escape hatch	ao.request(method, path, request)	Any v2 path the SDK does not model yet (any base with the five-argument form).

Each method's Javadoc 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 call apiKey(...) or dotenv(...) on the builder.

AuthenticationError (401)

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

ConfigurationError: ... base 'ai_chat' has no URL configured

Call aiChatBaseUrl(...) on the builder. The AI chat backend has no public default.

TransportError: ... Unable to establish loopback connection (Windows)

The JDK's HttpClient binds an AF_UNIX socket in the temp directory, and some temp paths (8.3 short names) refuse it. Start the JVM with -Djdk.net.unixdomain.tmpdir= set to a normal directory.

Need help?

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