# Service Sentinel API

The **Service Sentinel** is a high-performance observability engine designed for the SpaceKeep ecosystem. It provides real-time health monitoring and automated incident response for distributed systems.

## Overview

Unlike traditional monitoring tools that poll services at fixed intervals, the Service Sentinel uses a push-based telemetry model combined with a sub-second anomaly detection engine.

## Core Features

### 1. Adaptive Thresholding
Sentinel learns the "normal" latency patterns of your API and only triggers alerts when performance deviates from the historical baseline, reducing alert fatigue.

### 2. Automated Circuit Breaking
If Sentinel detects a consecutive run of 5xx errors, it can automatically trigger a circuit breaker to protect downstream services and redirect traffic to a failover cluster.

---

## API Reference

### Watch Endpoint
`POST /v1/sentinel/watch`

Monitors a specific target URL and registers a webhook for alert notifications.

**Request Body**
```json
{
  "target_url": "https://api.myapp.com/health",
  "interval": "30s",
  "threshold": 0.95,
  "webhook": "https://hooks.spacekeep.dev/alerts/123"
}
```

**Response Codes**
- `200 OK`: Watcher successfully registered.
- `401 Unauthorized`: Invalid API Key.
- `429 Too Many Requests`: Rate limit exceeded for your tier.

---

## Implementation Example

```typescript
// Registering a new service with the Sentinel
const response = await fetch('https://api.spacekeep.dev/v1/sentinel/watch', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.SK_API_KEY}`
  },
  body: JSON.stringify({
    target_url: 'https://prod-1.spacekeep.app/status',
    interval: '10s'
  })
});
```

---

**Pro Tip:** You can combine Sentinel with our internal load balancers to automatically scale up replica sets when latency exceeds the `p99` threshold.