---
name: umami
description: Self-hosted Umami Analytics integration with username/password authentication. Use to create websites, get tracking codes, and fetch analytics data.
---

# 📊 Umami Analytics Skill

**Skill Name:** `umami`  
**Category:** `quick`  
**Load Skills:** `[]`

---

## 🚀 Purpose

Integrate with self-hosted Umami Analytics using username/password authentication (like Easypanel):

- ✅ **Auto-login** - Get bearer token from credentials
- ✅ **Create websites** - Auto-create Umami website for new projects
- ✅ **Get tracking code** - Retrieve script URL for website integration
- ✅ **Fetch analytics** - Get pageviews, visitors, bounce rate
- ✅ **List websites** - Get all websites in Umami instance

**Use Cases:**
1. Auto-create Umami website when generating new website
2. Add tracking code to Astro website automatically
3. Fetch analytics data for SEO analysis
4. Manage multiple Umami websites

---

## 📋 Pre-Flight Questions

**MUST ask before using:**

1. **Umami Instance URL:**
   - What's your Umami URL? (e.g., https://analytics.moreminimore.com)

2. **Authentication:**
   - Username/email
   - Password

3. **For Website Creation:**
   - Website name
   - Website domain

4. **For Existing Website:**
   - Website name or domain (to find in Umami)

---

## 🔄 Workflows

### **Workflow 1: Auto-Login (First Step for All Operations)**

```python
Input: Umami URL, username, password
Process:
  1. POST /api/auth/login
  2. Get bearer token
  3. Save token for subsequent requests
Output: Bearer token + user info
```

### **Workflow 2: Create Umami Website**

```python
Input: Website name, domain
Process:
  1. Login (get token)
  2. POST /api/websites
  3. Get website ID
Output: Website ID, name, domain, tracking URL
```

### **Workflow 3: Get Tracking Code**

```python
Input: Website ID or domain
Process:
  1. Get website ID
  2. Generate tracking script URL
Output: Script tag or URL
```

### **Workflow 4: Add Tracking to Website**

```python
Input: Website repo path, Umami website ID
Process:
  1. Get tracking code
  2. Find Astro root layout
  3. Add script to <head>
  4. Save file
Output: Updated layout file
```

### **Workflow 5: Fetch Analytics**

```python
Input: Website ID, date range
Process:
  1. GET /api/websites/:id/stats
  2. Parse response
Output: Pageviews, visitors, bounce rate, etc.
```

---

## 🔧 Technical Implementation

### **Authentication:**

```python
POST {umami_url}/api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "username": "admin",
    "isAdmin": true
  }
}
```

### **Create Website:**

```python
POST {umami_url}/api/websites
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My Website",
  "domain": "example.com"
}

Response:
{
  "id": "website-uuid",
  "name": "My Website",
  "domain": "example.com",
  "createdAt": "2026-03-08T..."
}
```

### **Get Tracking Code:**

```javascript
// Script URL format
<script defer src="{umami_url}/script.js" data-website-id="{website_id}"></script>

// Or for Fathom-style (if enabled)
<script defer src="{umami_url}/script.js" data-site-id="{website_id}"></script>
```

### **Get Stats:**

```python
GET {umami_url}/api/websites/{website_id}/stats
  ?startAt={timestamp}
  &endAt={timestamp}
Authorization: Bearer {token}

Response:
{
  "pageviews": 1234,
  "uniques": 567,
  "bounces": 89,
  "totaltime": 12345
}
```

---

## 📁 Commands

### **Create Umami Website:**

```bash
python3 skills/umami/scripts/umami_client.py \
  --action create-website \
  --umami-url "https://analytics.moreminimore.com" \
  --username "admin" \
  --password "your-password" \
  --website-name "My Website" \
  --website-domain "example.com"
```

### **Get Tracking Code:**

```bash
python3 skills/umami/scripts/umami_client.py \
  --action get-tracking \
  --umami-url "https://analytics.moreminimore.com" \
  --username "admin" \
  --password "your-password" \
  --website-id "website-uuid"
```

### **Add Tracking to Website:**

```bash
python3 skills/umami/scripts/umami_client.py \
  --action add-tracking \
  --umami-url "https://analytics.moreminimore.com" \
  --username "admin" \
  --password "your-password" \
  --website-name "My Website" \
  --website-repo "/path/to/astro-website"
```

### **Fetch Analytics:**

```bash
python3 skills/umami/scripts/umami_client.py \
  --action get-stats \
  --umami-url "https://analytics.moreminimore.com" \
  --username "admin" \
  --password "your-password" \
  --website-id "website-uuid" \
  --days 30
```

---

## ⚙️ Environment Variables

**Updated for username/password auth:**

```bash
# Umami Analytics (Self-Hosted)
UMAMI_URL=https://analytics.yoursite.com
UMAMI_USERNAME=admin
UMAMI_PASSWORD=your-password
```

**Note:** Changed from API key to username/password like Easypanel

---

## 📊 Output Examples

### **Create Website Output:**

```json
{
  "success": true,
  "website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "My Website",
  "domain": "example.com",
  "tracking_url": "https://analytics.moreminimore.com/script.js",
  "tracking_script": "<script defer src=\"https://analytics.moreminimore.com/script.js\" data-website-id=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"></script>",
  "created_at": "2026-03-08T16:00:00.000Z"
}
```

### **Stats Output:**

```json
{
  "success": true,
  "website_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "period": "last_30_days",
  "stats": {
    "pageviews": 12500,
    "uniques": 8900,
    "bounces": 1200,
    "totaltime": 245000,
    "avg_session_duration": 27.5,
    "bounce_rate": 13.5
  }
}
```

---

## 🔄 Integration with Other Skills

### **website-creator Integration:**

```python
# After creating Astro website
umami_result = create_umami_website(
    umami_url, username, password,
    website_name, website_domain
)

if umami_result['success']:
    # Add tracking to Astro layout
    add_tracking_to_astro(
        website_repo,
        umami_result['tracking_script']
    )
```

### **seo-data Integration:**

```python
# Replace umami_connector.py stub
from umami import UmamiClient

umami = UmamiClient(umami_url, username, password)
stats = umami.get_page_data(website_id, days=30)
```

---

## ✅ Success Criteria

- [ ] Can login with username/password
- [ ] Can create new Umami website
- [ ] Can get tracking code
- [ ] Can add tracking to Astro website
- [ ] Can fetch analytics data
- [ ] Token cached for subsequent requests

---

## ⚠️ Important Notes

1. **Self-Hosted Only:** This skill is for self-hosted Umami instances
2. **Username/Password:** Uses login API, not API keys (Umami Cloud uses API keys)
3. **Token Caching:** Bearer token should be cached to avoid repeated logins
4. **Website Domain:** Must be full domain (https://example.com)
5. **Script URL:** Depends on Umami instance URL

---

## 📖 API Reference

- **Login:** POST /api/auth/login
- **Create Website:** POST /api/websites
- **Get Website:** GET /api/websites/:id
- **Get Stats:** GET /api/websites/:id/stats
- **List Websites:** GET /api/websites

Full docs: https://umami.is/docs/api

---

**Use this skill when you need to integrate with self-hosted Umami Analytics using username/password authentication.**
