AnomalyArmor API Overview

AnomalyArmor provides a REST API for programmatic access to data observability features. This enables automation, CI/CD integration, and custom tooling.

Base URL

https://api.anomalyarmor.ai/api/v1

Authentication

All API requests require authentication via API key. Include your key in the Authorization header:

curl -H "Authorization: Bearer aa_live_your_key_here" \
  https://api.anomalyarmor.ai/api/v1/assets

Create API keys in Settings > API Keys or via CLI: armor api-keys create

Rate Limiting

Rate limits are enforced per API key based on your subscription tier:

Tier	Rate Limit	Burst
Free Trial	20 req/min	2 req/sec
Starter	30 req/min	3 req/sec
Growth	500 req/min	25 req/sec
Professional	1,000 req/min	50 req/sec
Enterprise	5,000 req/min	100 req/sec

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1701705600

When rate limited, you’ll receive a 429 response with Retry-After header.

Pagination

All list endpoints use offset/limit pagination:

GET /api/v1/assets?limit=50&offset=100

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 245,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

Error Responses

Errors return a consistent JSON structure:

{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "Asset not found",
    "details": {
      "asset_id": "snowflake.prod.warehouse.orders",
      "suggestion": "Check the qualified name format: source.database.schema.table"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`ASSET_NOT_FOUND`	404	Asset doesn’t exist or not accessible
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Valid key but insufficient scope
`RATE_LIMITED`	429	Too many requests
`VALIDATION_ERROR`	400	Invalid request parameters
`INTERNAL_ERROR`	500	Server error

Quick Start

from anomalyarmor import Client

# Initialize with API key
client = Client(api_key="aa_live_xxx")

# List assets
assets = client.assets.list(source="snowflake", limit=10)
for asset in assets:
    print(asset.qualified_name)

# Check freshness (raises StalenessError if stale)
client.freshness.require_fresh("snowflake.prod.warehouse.orders")

# List assets
curl -H "Authorization: Bearer aa_live_xxx" \
  "https://api.anomalyarmor.ai/api/v1/assets?limit=10"

# Get freshness status
curl -H "Authorization: Bearer aa_live_xxx" \
  "https://api.anomalyarmor.ai/api/v1/freshness?asset=snowflake.prod.warehouse.orders"

# List assets
armor assets list --source snowflake --limit 10

# Check freshness (exits 1 if stale)
armor freshness check snowflake.prod.warehouse.orders

Available Endpoints

Assets

List and retrieve data assets

Freshness

Monitor and check data freshness

Schema

Track schema changes and drift

Lineage

Explore data dependencies

Alerts

Query alert history and status

Authentication

API key management

Data Quality APIs

Metrics

Track row counts, null rates, and data trends

Validity

Enforce NOT NULL, UNIQUE, REGEX, and custom rules

Referential Checks

Verify foreign key relationships

Next Steps

SDK Quickstart

Get started with the Python SDK

CLI Reference

Command-line interface guide

Airflow Integration

Use with Apache Airflow

Common Questions

What is the base URL for the AnomalyArmor API?

All endpoints are served from https://api.anomalyarmor.ai/api/v1. Every request must include a Bearer token in the Authorization header. Point the Python or TypeScript SDK at a different api_url / baseUrl if you are targeting a staging environment.

How do I handle rate limits and 429 responses?

Limits are per-API-key and vary by subscription tier, from 20 req/min on Free Trial up to 5,000 req/min on Enterprise. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, and 429s include a Retry-After header you should honor before retrying. The TypeScript SDK retries idempotent requests automatically; the Python SDK raises RateLimitError with a retry_after attribute.

How does pagination work on list endpoints?

List endpoints use offset/limit pagination with limit (default 50, max 100) and offset query parameters. Responses include a pagination object with total, limit, offset, and has_more so you can loop until has_more is false. Prefer paging in batches of 100 to minimize request count against your rate limit.

What error codes does the API return?

Errors come back as {"error": {"code", "message", "details"}}. Common codes include ASSET_NOT_FOUND (404), UNAUTHORIZED (401), FORBIDDEN (403), RATE_LIMITED (429), VALIDATION_ERROR (400), and INTERNAL_ERROR (500). The details object usually includes field names or suggestions you can surface in logs.

Should I use the REST API directly or the SDK?

Use the SDK in application code: it handles auth, retries on 429, and typed responses for you. Hit the REST API directly from shell scripts, non-supported languages, or when you need a verb not yet wrapped by the ergonomic SDK surface. Both paths share the same aa_live_* Bearer token.

API Overview

API Reference

API Guides

SDKs

CLI

Integrations

AI Agents

AnomalyArmor API Overview

Base URL

Authentication

Rate Limiting

Rate Limit Headers

Error Responses

Error Codes

Quick Start

Available Endpoints

Assets

Freshness

Schema

Lineage

Alerts

Authentication

Data Quality APIs

Metrics

Validity

Referential Checks

Next Steps

SDK Quickstart

CLI Reference

Airflow Integration

Common Questions

What is the base URL for the AnomalyArmor API?

How do I handle rate limits and 429 responses?

What error codes does the API return?

Should I use the REST API directly or the SDK?

​Base URL

​Authentication

​Rate Limiting

​Rate Limit Headers

​Pagination

​Error Responses

​Error Codes

​Quick Start

​Available Endpoints

Assets

Freshness

Schema

Lineage

Alerts

Authentication

​Data Quality APIs

Metrics

Validity

Referential Checks

​Next Steps

SDK Quickstart

CLI Reference

Airflow Integration

​Common Questions

​What is the base URL for the AnomalyArmor API?

​How do I handle rate limits and 429 responses?

​How does pagination work on list endpoints?

​What error codes does the API return?

​Should I use the REST API directly or the SDK?

Base URL

Authentication

Rate Limiting

Rate Limit Headers

Pagination

Error Responses

Error Codes

Quick Start

Available Endpoints

Data Quality APIs

Next Steps

Common Questions

What is the base URL for the AnomalyArmor API?

How do I handle rate limits and 429 responses?

How does pagination work on list endpoints?

What error codes does the API return?

Should I use the REST API directly or the SDK?