API Documentation

Complete reference for the AnomalyWatch REST API v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer aw_live_your_api_key_here

API keys can be generated from your Dashboard. Use aw_test_ prefix for sandbox and aw_live_ for production.

Base URL

https://api.anomalywatch.dev

Rate Limits

Free: 100 req/min

Pro: 1,000 req/min

Enterprise: 10,000 req/min

Endpoints

POST/v1/ingest

Ingest time series data points for anomaly detection

Request Body

{
  "metric": "cpu_usage",
  "value": 94.2,
  "timestamp": "2026-03-27T12:00:00Z",
  "tags": { "host": "api-gw-01", "region": "us-east-1" }
}

Response

{
  "status": "ingested",
  "anomaly_score": 0.92,
  "severity": "critical",
  "baseline": { "mean": 45.3, "std": 8.7 }
}
GET/v1/anomalies

Retrieve detected anomalies with filtering and pagination

Response

{
  "anomalies": [
    {
      "id": "anom_8x7k2m",
      "metric": "cpu_usage",
      "score": 0.92,
      "severity": "critical",
      "detected_at": "2026-03-27T12:00:01Z",
      "value": 94.2,
      "expected_range": [32.1, 58.5]
    }
  ],
  "total": 47,
  "page": 1
}
POST/v1/forecast

Generate time series forecasts using AI models

Request Body

{
  "metric": "request_rate",
  "horizon": "24h",
  "model": "timesfm-v2",
  "confidence": 0.95
}

Response

{
  "forecast": [
    { "timestamp": "2026-03-28T00:00:00Z", "value": 1247.3, "lower": 1102.1, "upper": 1392.5 },
    { "timestamp": "2026-03-28T01:00:00Z", "value": 892.1, "lower": 761.4, "upper": 1022.8 }
  ],
  "model": "timesfm-v2",
  "confidence": 0.95
}
GET/v1/metrics/:id

Get metric details, history, and anomaly statistics

Response

{
  "id": "met_cpu01",
  "name": "cpu_usage",
  "tags": { "host": "api-gw-01" },
  "stats": {
    "anomalies_24h": 3,
    "mean": 45.3,
    "p99": 78.2,
    "last_value": 47.1
  }
}

Code Examples

Ingest Data

import requests

resp = requests.post(
    "https://api.anomalywatch.dev/v1/ingest",
    headers={"Authorization": "Bearer aw_live_xxxx"},
    json={
        "metric": "cpu_usage",
        "value": 94.2,
        "timestamp": "2026-03-27T12:00:00Z",
        "tags": {"host": "api-gw-01"}
    }
)
print(resp.json())  # {"anomaly_score": 0.92, ...}

Data Format

AnomalyWatch accepts JSON time series data with the following schema:

{
  "metric": "string (required) — metric name",
  "value": "number (required) — observed value",
  "timestamp": "string (required) — ISO 8601 timestamp",
  "tags": "object (optional) — key-value metadata pairs",
  "source": "string (optional) — data source identifier"
}