Skip to main content
@anomalyarmor/sdk is the official TypeScript SDK for AnomalyArmor. Types are generated straight from our OpenAPI spec via openapi-typescript, so every endpoint is typed end-to-end. Runtime is a thin wrapper around openapi-fetch with Bearer auth and retry-on-429 middleware baked in.

​
Install

npm install @anomalyarmor/sdk
# or: pnpm add @anomalyarmor/sdk  /  yarn add @anomalyarmor/sdk
Node 18+ is required. The package ships dual ESM + CJS builds and TypeScript types.

​
Quickstart

import { createAnomalyArmorClient } from '@anomalyarmor/sdk';

const client = createAnomalyArmorClient({
  apiKey: process.env.ANOMALYARMOR_API_KEY!, // aa_live_...
});

// Liveness probe — 200 means key is valid
const health = await client.health.check();

// Aggregate counts of open alerts
const overview = await client.alerts.overview();
console.log(`${overview.unresolved_alerts} unresolved alerts`);

// Per-table freshness for an asset
const freshness = await client.freshness.check('asset-uuid-here');
Get an API key at app.anomalyarmor.ai/settings/api-keys. Keys start with aa_live_.

​
Authentication

The SDK captures your API key at construction time and attaches Authorization: Bearer <key> to every outgoing request via a small middleware. The SDK library itself never reads from process.env — that would hide auth at a distance. Only the CLI shim (next section) reads ANOMALYARMOR_API_KEY, because CLIs traditionally do.
Bearer auth flow

​
CLI

The package ships a bin binary so you can smoke-check connectivity without writing code: 
# With the env var set:
export ANOMALYARMOR_API_KEY=aa_live_...
npx anomalyarmor health

# Or pass the key directly:
npx anomalyarmor health --api-key aa_live_...
The CLI has exactly one command (health) by design — anything richer belongs in a real script calling the library API.

​
Rate limiting & retries

The SDK automatically retries HTTP 429 responses, honoring Retry-After. Retries are bounded (default 3 attempts, each sleep capped at 60 s) and only apply to idempotent verbs (GET, HEAD, PUT, DELETE, OPTIONS) so a POST failure never duplicates a side effect.
Retry-on-429 flow
Tune or disable: 
const client = createAnomalyArmorClient({
  apiKey: '...',
  maxRetries: 5,              // default 3
  maxRetrySleepSeconds: 120,  // default 60
});

// Opt out of retries entirely (mutation-heavy callers who want explicit control):
const client = createAnomalyArmorClient({ apiKey: '...', maxRetries: 0 });

​
How requests work

Every typed SDK call flows through six layers: the ergonomic helper → openapi-fetch → the middleware stack → platform fetch → parse / unwrap → a statically-typed response.
Request lifecycle

​
Error handling

Ergonomic methods throw AnomalyArmorApiError on 4xx / 5xx responses: 
import { AnomalyArmorApiError } from '@anomalyarmor/sdk';

try {
  await client.alerts.get('does-not-exist');
} catch (err) {
  if (err instanceof AnomalyArmorApiError) {
    console.error(`HTTP ${err.status}: ${err.message}`);
    console.error('Full body:', err.body);
  } else {
    throw err; // network / parse / programmer errors
  }
}
The ergonomic surface covers the endpoints customers use most often. For anything else, client.raw exposes the full typed openapi-fetch client: 
const { data, error } = await client.raw.GET('/api/v1/assets/{asset_id}', {
  params: { path: { asset_id: 'my-asset' } },
});
if (error) throw new Error(`asset lookup failed: ${error.message}`);
// data is typed from the OpenAPI spec

​
Configuration reference

OptionDefaultPurpose
apiKey(required)Your aa_live_* Bearer token.
baseUrlhttps://app.anomalyarmor.aiOverride for staging or a local backend.
maxRetries3429-retry budget. Set to 0 to disable.
maxRetrySleepSeconds60Cap on any single Retry-After sleep.
fetchglobalThis.fetchInjectable fetch for tests / alternate runtimes.

​
Next steps

API reference

Full typed reference for every SDK method

Authentication

How API keys work across the platform

Python SDK

Same API surface in Python

CLI reference

Installable CLI for interactive use