Anomalies API - MeshAI Documentation

The expanded anomaly pipeline is live. API PR #84 activated the in-app five-minute scheduler on August 11, 2026. Production verification at the 20:20, 20:25, and 20:30 UTC boundaries observed exactly one elected runner per boundary, cycle times of 655 ms, 350 ms, and 490 ms, and no errors. The first cycle created 13 continuity incidents from existing evidence gaps; the next two created no duplicate incidents.

Detection semantics

Reliability baselines are source-specific: proxy and OTLP facts are not blended. Error-rate evaluation requires at least 10 baseline requests and 5 recent requests. Latency evaluation requires at least 10 baseline samples, 5 recent samples, and at least 50% duration coverage in both windows. Missing or invalid duration samples do not prevent error-rate evaluation. When latency is eligible, details.latency_statistic is mean_of_exact_5m_bucket_p95. MeshAI computes an exact p95 within each five-minute bucket, then compares the mean of those bucket values across the baseline and recent windows. This is not an exact percentile across all requests in the full window. details also reports source, sample counts, coverage, and whether error-rate and latency evidence were available.

List Anomalies

GET /anomalies

Parameter	Type	Description
`status`	string	`open`, `acknowledged`, `resolved`
`type`	string	`cost_spike`, `reliability_decay`, `behavioral_drift`, `security_threat`
`agent_id`	string	Filter to a specific agent
`severity`	string	`low`, `medium`, `high`, `critical`
`page`	integer	Page number
`limit`	integer	Results per page

curl "https://api.meshai.dev/api/v1/anomalies?status=open&type=cost_spike" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "ano_abc123",
      "agent_id": "agt_xyz789",
      "agent_name": "production-summarizer",
      "anomaly_type": "cost_spike",
      "severity": "high",
      "status": "open",
      "description": "Token spend increased 340% vs 7-day average",
      "detected_at": "2026-03-17T09:45:00Z",
      "details": {
        "current_cost_usd": 45.20,
        "baseline_cost_usd": 10.30,
        "deviation_percent": 338.8
      }
    }
  ],
  "meta": { "total": 3, "page": 1, "limit": 20 }
}

Get an Anomaly

GET /anomalies/{anomaly_id}

curl https://api.meshai.dev/api/v1/anomalies/ano_abc123 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Anomaly Summary

GET /anomalies/summary

Get counts by status and type.

curl https://api.meshai.dev/api/v1/anomalies/summary \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "total": 12,
    "by_status": { "open": 3, "acknowledged": 5, "resolved": 4 },
    "by_type": {
      "cost_spike": 6,
      "reliability_decay": 3,
      "behavioral_drift": 2,
      "security_threat": 1
    }
  }
}

Acknowledge an Anomaly

POST /anomalies/{anomaly_id}/acknowledge

curl -X POST https://api.meshai.dev/api/v1/anomalies/ano_abc123/acknowledge \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Expected spike, batch processing job" }'

Resolve an Anomaly

POST /anomalies/{anomaly_id}/resolve

curl -X POST https://api.meshai.dev/api/v1/anomalies/ano_abc123/resolve \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resolution": "Batch job completed. Cost back to normal." }'

Anomaly Rules

Custom rules let you define thresholds and conditions for anomaly detection beyond the built-in ML algorithms.

List Rules

GET /anomaly-rules

curl https://api.meshai.dev/api/v1/anomaly-rules \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Create a Rule

POST /anomaly-rules

Field	Type	Description
`anomaly_type`	string	`cost_spike`, `reliability_decay`, `behavioral_drift`, `security_threat`
`enabled`	boolean	Defaults to `true`
`threshold_config`	object	Threshold parameters for the rule
`notification_config`	object	Optional. Set `webhook_url` to receive delivery notifications

curl -X POST https://api.meshai.dev/api/v1/anomaly-rules \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "anomaly_type": "cost_spike",
    "enabled": true,
    "threshold_config": { "daily_cost_usd": 100 },
    "notification_config": { "webhook_url": "https://example.com/webhooks/meshai" }
  }'

{
  "success": true,
  "data": {
    "id": 12,
    "anomaly_type": "cost_spike",
    "enabled": true,
    "threshold_config": { "daily_cost_usd": 100 },
    "notification_config": { "webhook_url": "https://example.com/webhooks/meshai" },
    "created_at": "2026-03-17T10:00:00Z",
    "updated_at": "2026-03-17T10:00:00Z"
  }
}

Update a Rule

PATCH /anomaly-rules/{rule_id}

curl -X PATCH https://api.meshai.dev/api/v1/anomaly-rules/12 \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "threshold_config": { "daily_cost_usd": 150 } }'

Delete a Rule

DELETE /anomaly-rules/{rule_id}

curl -X DELETE https://api.meshai.dev/api/v1/anomaly-rules/12 \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

​Detection semantics

​List Anomalies

​Get an Anomaly

​Anomaly Summary

​Acknowledge an Anomaly

​Resolve an Anomaly

​Anomaly Rules

​List Rules

​Create a Rule

​Update a Rule

​Delete a Rule

Detection semantics

List Anomalies

Get an Anomaly

Anomaly Summary

Acknowledge an Anomaly

Resolve an Anomaly

Anomaly Rules

List Rules

Create a Rule

Update a Rule

Delete a Rule