# API Reference

The APM blueprint exposes REST
APIs through two services that are accessible via the NGINX reverse proxy at
`http://localhost:8080`.

## Storage Service

The storage service manages detection data written by the agent service and queried by the agent
pipeline.

**Base URL**: `http://localhost:8080/api/storage/`

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/detections` | Insert a single detection record |
| `POST` | `/detections/batch` | Bulk insert multiple detections |
| `GET` | `/detections` | Query detections — supports `label`, `min_confidence`, and `limit` filters |
| `GET` | `/detections/summary` | Per-class detection statistics |
| `DELETE` | `/detections` | Clear all stored detections |
| `GET` | `/health` | Health check endpoint |
| `GET` | `/metrics` | Prometheus metrics |

### Example: Insert a Detection

```bash
curl -X POST http://localhost:8080/api/storage/detections \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Rupture",
    "confidence": 0.87,
    "bbox": [120, 45, 300, 200],
    "frame_id": 42,
    "timestamp": "2026-06-25T10:00:00Z"
  }'
```

### Example: Query Detections by Label

```bash
curl "http://localhost:8080/api/storage/detections?label=Rupture&min_confidence=0.7&limit=20"
```

### Example: Get Detection Summary

```bash
curl http://localhost:8080/api/storage/detections/summary
```

Sample response:

```json
{
  "total": 120,
  "by_class": {
    "Rupture": 30,
    "Deformation": 55,
    "Disconnect": 10,
    "Obstacle": 25
  },
  "avg_confidence": 0.74
}
```

## Agent Service

The agent service triggers the multi-agent LangGraph pipeline and tracks run results.

**Base URL**: `http://localhost:8080/api/agents/`

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/runs` | Trigger a new agent pipeline run (asynchronous) |
| `GET` | `/runs` | List all agent runs |
| `GET` | `/runs/{run_id}` | Get the status and result of a specific run |
| `GET` | `/health` | Health check endpoint |
| `GET` | `/metrics` | Prometheus metrics |

### Example: Trigger an Agent Run

```bash
curl -X POST http://localhost:8080/api/agents/runs \
  -H "Content-Type: application/json" \
  -d '{}'
```

Response:

```json
{
  "run_id": "abc123",
  "status": "started"
}
```

### Example: Check Run Status

```bash
curl http://localhost:8080/api/agents/runs/abc123
```

When the run completes, the response includes the full ticket generated by the Ticketing Agent:

```json
{
  "run_id": "abc123",
  "status": "completed",
  "ticket": {
    "priority": "HIGH",
    "title": "Rupture detected in pipeline segment A3",
    "description": "Multiple high-confidence Rupture detections observed over 30 frames.",
    "affected_component": "segment-A3",
    "recommended_action": "HALT_PIPELINE",
    "estimated_resolution_time": "4 hours",
    "tags": ["Rupture", "Disconnect"]
  }
}
```

## Prometheus Metrics

The metrics-manager service collects metrics from both services and makes them available at:

- **Storage service**: `http://localhost:9091/metrics` — exposes `apm_storage_detections_total`
- **Agent service**: `http://localhost:9091/metrics` — exposes `apm_agent_runs_total`
  and `apm_agent_runs_completed`
- **Prometheus UI**: `http://localhost:9090`