time-series-dashboard

# time-series-dashboard skill

This skill covers all HTTP API operations for the time-series-dashboard application.

## Authentication flow

All admin routes require a session cookie obtained from login. Ingest routes require a Bearer API key.

```bash
# 1. Get CSRF token
CSRF=$(curl -s http://localhost:3000/api/csrf | jq -r '.token')

# 2. Log in (obtain session cookie)
curl -c /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"password": "your-admin-password"}'
```

## API keys

```bash
# List API keys (admin)
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/keys

# Create a new API key (raw key shown only once in response)
CSRF=$(curl -b /tmp/tsd_cookies.txt -s http://localhost:3000/api/csrf | jq -r '.token')
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/keys \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"name": "production-server"}'

# Revoke an API key
curl -b /tmp/tsd_cookies.txt -X DELETE http://localhost:3000/api/keys/key_abc123 \
  -H "X-CSRF-Token: $CSRF"
```

## Metrics CRUD

```bash
# List all metrics
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/metrics

# Create a metric
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/metrics \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{
    "name": "cpu_usage",
    "slug": "cpu_usage",
    "type": "gauge",
    "unit": "%",
    "color": "#0891b2",
    "description": "CPU utilization percentage"
  }'

# Update a metric
curl -b /tmp/tsd_cookies.txt -X PATCH http://localhost:3000/api/metrics/cpu_usage \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"description": "Updated description"}'

# Delete a metric (also deletes all data points)
curl -b /tmp/tsd_cookies.txt -X DELETE http://localhost:3000/api/metrics/cpu_usage \
  -H "X-CSRF-Token: $CSRF"
```

## Dashboards CRUD

```bash
# List dashboards
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/dashboards

# Create a dashboard
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/dashboards \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"name": "Production Overview", "defaultRange": "1h"}'

# Get a dashboard with panels
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/dashboards/dash_abc123

# Add a panel to a dashboard
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/dashboards/dash_abc123/panels \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{
    "title": "CPU Usage",
    "metricId": "cpu_usage",
    "chartType": "stat",
    "width": "half"
  }'

# Delete a dashboard
curl -b /tmp/tsd_cookies.txt -X DELETE http://localhost:3000/api/dashboards/dash_abc123 \
  -H "X-CSRF-Token: $CSRF"
```

## Alert rules

```bash
# List alert rules
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/alerts

# Create an alert rule
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/alerts \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{
    "name": "High Error Rate",
    "metricId": "error_rate",
    "condition": "gt",
    "threshold": 1.5,
    "enabled": 1
  }'

# Toggle a rule on/off
curl -b /tmp/tsd_cookies.txt -X PATCH http://localhost:3000/api/alerts/rule_xyz \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"enabled": 0}'

# List alert events
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/alerts/events

# List events for a specific rule
curl -b /tmp/tsd_cookies.txt http://localhost:3000/api/alerts/rule_xyz/events
```

## Querying time-series data

```bash
# Raw data - last 1 hour
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/metrics/cpu_usage/data?from=-1h"

# 5-minute averages over last 24 hours
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/metrics/cpu_usage/data?from=-24h&aggregation=avg&bucket=5m"

# Max over last 7 days with limit
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/metrics/cpu_usage/data?from=-7d&aggregation=max&bucket=1h&limit=168"

# Ad-hoc multi-metric query
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/query?metrics=cpu_usage,request_rate&from=-1h&aggregation=avg&bucket=5m"
```

## Export

```bash
# Export metric as CSV
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/export?metricId=cpu_usage&from=-7d&format=csv" \
  -o cpu_usage_export.csv

# Export as JSON
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/export?metricId=cpu_usage&from=-24h&format=json" \
  -o cpu_usage_export.json

# Export all metrics
curl -b /tmp/tsd_cookies.txt \
  "http://localhost:3000/api/export?from=-30d&format=json" \
  -o all_metrics_export.json
```

## Settings

```bash
# Change admin password
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/settings/password \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"currentPassword": "old-password", "newPassword": "new-password"}'

# Update retention period (days)
curl -b /tmp/tsd_cookies.txt -X PATCH http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"retentionDays": 60}'

# Log out
curl -b /tmp/tsd_cookies.txt -X POST http://localhost:3000/api/auth/logout \
  -H "X-CSRF-Token: $CSRF"
```

## Health check

```bash
curl http://localhost:3000/api/health
# {"status": "ok"}
```