umami-stats

# Umami Stats (Read-only API skill)

Use this skill as a **data-access layer**: fetch Umami analytics data, then let the agent decide analysis/strategy.

## Required environment variables

- `UMAMI_API_KEY` (required)
- `UMAMI_BASE_URL` (optional, default: `https://api.umami.is`)
- `UMAMI_WEBSITE_ID` (optional default site)
- `UMAMI_DEPLOYMENT` (optional: `cloud` or `self-hosted`, default: `cloud`)

## API path conventions (explicit)

- **Umami Cloud:** `https://api.umami.is/v1/...`
- **Self-hosted Umami:** `https://<your-host>/api/...`

The script supports both:
- `--deployment cloud` → uses cloud behavior (`/v1` + `x-umami-api-key`)
- `--deployment self-hosted` → uses self-hosted behavior (`/api` + `Authorization: Bearer ...`)

## Read-only workflow

1. Pick endpoint from docs or `references/read-endpoints.md`.
2. Run `scripts/umami_query.py` with endpoint + params.
3. Use presets (`today`, `last7d`, etc.) or custom `startAt`/`endAt`.
4. Analyze returned JSON for the user task.

## Quick commands

```bash
# 1) List websites
python3 scripts/umami_query.py --endpoint /v1/websites

# 2) Website stats for last 7 days (default website from env)
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/stats \
  --preset last7d

# 3) Top pages with explicit website id
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/pageviews \
  --website-id "$UMAMI_WEBSITE_ID" \
  --preset last30d

# 4) Events series with custom window
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/events/series \
  --param startAt=1738368000000 \
  --param endAt=1738972799000

# 5) Legacy path auto-mapping in cloud mode (/api/... -> /v1/...)
python3 scripts/umami_query.py --endpoint /api/websites/{websiteId}/stats --preset last7d

# 6) Self-hosted example (/v1/... auto-maps to /api/...)
python3 scripts/umami_query.py \
  --deployment self-hosted \
  --base-url "https://umami.example.com" \
  --endpoint /v1/websites/{websiteId}/stats \
  --pre...