<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Implementing Purple Team Metrics Dashboard

## Grafana API

| Endpoint | Method | Description |
|---|---|---|
| `/api/dashboards/db` | POST | Create/update dashboard |
| `/api/dashboards/uid/{uid}` | GET | Get dashboard by UID |
| `/api/search` | GET | Search dashboards |
| `/api/datasources` | GET | List data sources |
| `/api/datasources` | POST | Add data source |

### Create Dashboard Request

```json
{
  "dashboard": {
    "title": "Purple Team Metrics",
    "panels": [{"title": "Coverage", "type": "gauge"}]
  },
  "overwrite": true
}
```

## Prometheus

| Endpoint | Method | Description |
|---|---|---|
| `/api/v1/query` | GET | Instant query |
| `/api/v1/query_range` | GET | Range query |
| `/metrics/job/{job}` | POST | Push metrics (pushgateway) |

### Metric Names

| Metric | Type | Description |
|---|---|---|
| `purple_team_detection_coverage_pct` | gauge | Detection coverage % |
| `purple_team_mttd_avg_seconds` | gauge | Average MTTD |
| `purple_team_mttr_avg_seconds` | gauge | Average MTTR |
| `purple_team_control_bypass_rate_pct` | gauge | Bypass rate % |

## InfluxDB v2

| Endpoint | Method | Description |
|---|---|---|
| `/api/v2/write` | POST | Write data points |
| `/api/v2/query` | POST | Query with Flux |
| `/api/v2/buckets` | GET | List buckets |

## Agent Script

```bash
# Collect metrics
node agent.js collect-metrics --exercise-results results/ \
  --siem-url https://splunk:8089 --output metrics/q1.json

# Push to Prometheus
node agent.js push-metrics --metrics metrics/q1.json \
  --prometheus-url http://localhost:9091

# Deploy dashboard
node agent.js deploy-dashboard --grafana-url http://localhost:3000 \
  --api-key "${GRAFANA_API_KEY}"

# Executive report
node agent.js executive-report --metrics metrics/q1.json \
  --output reports/executive.json

# Trend analysis
node agent.js trend-analysis --metrics metrics/q4.json metrics/q1.json \
  --output reports/trend.json
```
