docs: Add API docs link to admin dashboard, improve API reference (#21)

* docs: Add API docs link to admin dashboard, improve API reference

- Add "View API Documentation →" link in API Keys section of admin dashboard
- Replace localhost URLs with {base_url} placeholder throughout API docs
- Add Base URL section explaining how to configure for different environments
- Expand Authentication section with API key usage examples
- Document that API keys are managed via Admin Dashboard

* fix: Link to internal Swagger docs instead of external GitHub Pages

* feat: Improve API docs and add user-scoped CSV export endpoints

- Hide admin and OAuth routes from Swagger docs (internal use only)
- Add proper tags to all API routers (System, Sleep, Data, Sync, API Keys, Export)
- Add new user-scoped CSV export endpoints at /api/v1/users/{user_id}/export/*.csv
- Add Literal types with enum dropdowns for metric_name and pattern_name parameters
- Add examples and descriptions for date parameters (YYYY-MM-DD format)
- Fix admin CSV exports to filter by connected user's polar_user_id (multi-tenancy fix)

* docs: Update changelog and API docs for CSV export endpoints

- Add unreleased section to CHANGELOG with new features
- Document CSV export endpoints in API overview
- Include column descriptions for each CSV format

Author: StuMason

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+**User-Scoped CSV Export API**
+- New endpoints for programmatic CSV downloads:
+  - `GET /api/v1/users/{user_id}/export/sleep.csv`
+  - `GET /api/v1/users/{user_id}/export/activity.csv`
+  - `GET /api/v1/users/{user_id}/export/recharge.csv`
+  - `GET /api/v1/users/{user_id}/export/cardio-load.csv`
+- All exports support `days` query parameter (1-365, default 30)
+- Protected by per-user API key authentication
+
+**Improved OpenAPI Documentation**
+- Added proper tags to all API routers (System, Sleep, Data, Sync, API Keys, Export, Baselines, Patterns, Insights)
+- Added enum dropdowns for `metric_name` parameter (hrv_rmssd, sleep_score, resting_hr, training_load, training_load_ratio)
+- Added enum dropdowns for `pattern_name` parameter (sleep_hrv_correlation, overtraining_risk, hrv_trend, sleep_trend, etc.)
+- Added examples and descriptions for date parameters (YYYY-MM-DD format)
+- Added examples for exercise_id and anomaly check value parameters
+
+### Changed
+
+- Admin and OAuth routes hidden from Swagger docs (internal use only)
+- Admin CSV exports now filter by connected user's `polar_user_id` (multi-tenancy fix)
+
 ---
 
 ## [1.3.3] - 2026-01-21

docs/api/overview.md

@@ -2,7 +2,16 @@
 
 REST API for accessing synced Polar health data.
 
-Base URL: `http://localhost:8000/api/v1`
+## Base URL
+
+```
+{base_url}/api/v1
+```
+
+Replace `{base_url}` with your server address:
+- **Local development**: `http://localhost:8000`
+- **Docker**: `http://localhost:8000` or your configured port
+- **Production**: Your deployed server URL (e.g., `https://polar.example.com`)
 
 ## OpenAPI Specification
 
@@ -14,14 +23,28 @@ The full OpenAPI 3.1 specification is available at:
 
 ```bash
 # Download OpenAPI spec
-curl http://localhost:8000/schema/openapi.json > openapi.json
+curl {base_url}/schema/openapi.json > openapi.json
 ```
 
 ## Authentication
 
-All data endpoints require a `user_id` in the URL path. For self-hosted deployments, this is your Polar user ID. For SaaS integrations, this is your application's user identifier.
+### API Key Authentication
+
+If an API key is configured (recommended for production), include it in the `X-API-Key` header:
+
+```bash
+curl -H "X-API-Key: your_api_key_here" {base_url}/api/v1/users/12345/sleep
+```
+
+API keys can be created and managed from the **Admin Dashboard → API Keys** section.
+
+### User ID
+
+All data endpoints require a `user_id` in the URL path. For self-hosted deployments, this is your Polar user ID (visible in the admin dashboard). For SaaS integrations, this is your application's user identifier.
+
+### Sync Endpoints
 
-Sync endpoints require a Polar API access token via the `X-Polar-Token` header.
+Sync endpoints additionally require a Polar API access token via the `X-Polar-Token` header.
 
 ## Endpoints
 
@@ -37,7 +60,7 @@ Sync endpoints require a Polar API access token via the `X-Polar-Token` header.
 
 **Example:**
 ```bash
-curl http://localhost:8000/api/v1/users/12345/sleep?days=30
+curl {base_url}/api/v1/users/12345/sleep?days=30
 ```
 
 **Response:**
@@ -70,7 +93,7 @@ curl http://localhost:8000/api/v1/users/12345/sleep?days=30
 
 **Example:**
 ```bash
-curl http://localhost:8000/api/v1/users/12345/activity?days=7
+curl {base_url}/api/v1/users/12345/activity?days=7
 ```
 
 **Response:**
@@ -101,7 +124,7 @@ curl http://localhost:8000/api/v1/users/12345/activity?days=7
 
 **Example:**
 ```bash
-curl http://localhost:8000/api/v1/users/12345/recharge?days=14
+curl {base_url}/api/v1/users/12345/recharge?days=14
 ```
 
 **Response:**
@@ -132,7 +155,7 @@ curl http://localhost:8000/api/v1/users/12345/recharge?days=14
 
 **Example:**
 ```bash
-curl http://localhost:8000/api/v1/users/12345/exercises?days=30
+curl {base_url}/api/v1/users/12345/exercises?days=30
 ```
 
 **Response:**
@@ -289,7 +312,7 @@ Requires compatible device with Elixir sensor platform.
 ```bash
 curl -X POST \
   -H "X-Polar-Token: your_polar_token" \
-  http://localhost:8000/api/v1/users/12345/sync/trigger?days=30
+  {base_url}/api/v1/users/12345/sync/trigger?days=30
 ```
 
 **Response:**
@@ -320,10 +343,16 @@ curl -X POST \
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/users/{user_id}/export/summary` | Export summary manifest |
+| GET | `/users/{user_id}/export/sleep.csv` | Export sleep data as CSV |
+| GET | `/users/{user_id}/export/activity.csv` | Export activity data as CSV |
+| GET | `/users/{user_id}/export/recharge.csv` | Export recharge/HRV data as CSV |
+| GET | `/users/{user_id}/export/cardio-load.csv` | Export cardio load data as CSV |
 
 **Query Parameters:**
 - `days` (int, default: 30) - Number of days to include (1-365)
 
+#### Export Summary
+
 **Response:**
 ```json
 {
@@ -343,6 +372,25 @@ curl -X POST \
 }
 ```
 
+#### CSV Exports
+
+Download data as CSV files for use in spreadsheets, data analysis tools, or external systems.
+
+**Example:**
+```bash
+curl -H "X-API-Key: pfk_..." \
+  "{base_url}/api/v1/users/12345/export/sleep.csv?days=90" \
+  -o sleep_data.csv
+```
+
+**Sleep CSV columns:** `date`, `sleep_score`, `total_hours`, `deep_hours`, `light_hours`, `rem_hours`, `hrv_avg`, `heart_rate_avg`, `breathing_rate_avg`
+
+**Activity CSV columns:** `date`, `steps`, `calories_active`, `calories_total`, `distance_km`, `active_minutes`
+
+**Recharge CSV columns:** `date`, `hrv_avg`, `ans_charge`, `status`, `breathing_rate`, `heart_rate_avg`
+
+**Cardio Load CSV columns:** `date`, `strain`, `tolerance`, `cardio_load`, `load_ratio`, `status`
+
 ---
 
 ### Baselines & Analytics
@@ -367,7 +415,7 @@ Personal baselines computed from historical data. Use these for anomaly detectio
 #### Get All Baselines
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/baselines
+curl {base_url}/api/v1/users/12345/baselines
 ```
 
 **Response:**
@@ -409,7 +457,7 @@ Uses IQR-based anomaly detection:
 - **Critical**: value outside Q1 - 3×IQR to Q3 + 3×IQR
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/baselines/check/hrv_rmssd/25.5
+curl {base_url}/api/v1/users/12345/baselines/check/hrv_rmssd/25.5
 ```
 
 **Response:**
@@ -432,7 +480,7 @@ curl http://localhost:8000/api/v1/users/12345/baselines/check/hrv_rmssd/25.5
 Trigger baseline recalculation from historical data:
 
 ```bash
-curl -X POST http://localhost:8000/api/v1/users/12345/baselines/calculate
+curl -X POST {base_url}/api/v1/users/12345/baselines/calculate
 ```
 
 **Response:**
@@ -454,7 +502,7 @@ curl -X POST http://localhost:8000/api/v1/users/12345/baselines/calculate
 Check feature availability based on data history:
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/analytics/status
+curl {base_url}/api/v1/users/12345/analytics/status
 ```
 
 **Response:**
@@ -527,7 +575,7 @@ Advanced pattern detection for correlations, trends, and risk assessment.
 #### Get All Patterns
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/patterns
+curl {base_url}/api/v1/users/12345/patterns
 ```
 
 **Response:**
@@ -577,15 +625,15 @@ curl http://localhost:8000/api/v1/users/12345/patterns
 #### Get Specific Pattern
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/patterns/overtraining_risk
+curl {base_url}/api/v1/users/12345/patterns/overtraining_risk
 ```
 
 #### Trigger Pattern Detection
 
 Analyzes historical data and stores pattern results:
 
 ```bash
-curl -X POST http://localhost:8000/api/v1/users/12345/patterns/detect
+curl -X POST {base_url}/api/v1/users/12345/patterns/detect
 ```
 
 **Response:**
@@ -606,7 +654,7 @@ curl -X POST http://localhost:8000/api/v1/users/12345/patterns/detect
 Scans all metrics against stored baselines and returns any values outside normal bounds:
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/anomalies
+curl {base_url}/api/v1/users/12345/anomalies
 ```
 
 **Response:**
@@ -677,7 +725,7 @@ Features unlock progressively as more data becomes available:
 #### Example Request
 
 ```bash
-curl http://localhost:8000/api/v1/users/12345/insights
+curl {base_url}/api/v1/users/12345/insights
 ```
 
 #### Example Response (30+ days of data)

src/polar_flow_server/admin/__init__.py

@@ -4,6 +4,8 @@
 
 from polar_flow_server.admin.routes import admin_routes
 
-admin_router = Router(path="/admin", route_handlers=admin_routes, tags=["Admin"])
+admin_router = Router(
+    path="/admin", route_handlers=admin_routes, tags=["Admin"], include_in_schema=False
+)
 
 __all__ = ["admin_router"]

src/polar_flow_server/admin/routes.py

@@ -1575,12 +1575,20 @@ async def export_sleep_csv(
     session: AsyncSession,
     days: int = 30,
 ) -> Response[bytes] | Redirect:
-    """Export sleep data as CSV."""
+    """Export sleep data as CSV for the connected user."""
     if not is_authenticated(request):
         return Redirect(path="/admin/login", status_code=HTTP_303_SEE_OTHER)
 
+    # Get connected user to filter by user_id
+    connected_user_stmt = select(User).where(User.is_active == True).limit(1)  # noqa: E712
+    connected_user_result = await session.execute(connected_user_stmt)
+    connected_user = connected_user_result.scalar_one_or_none()
+
     since_date = date.today() - timedelta(days=days)
-    stmt = select(Sleep).where(Sleep.date >= since_date).order_by(Sleep.date.asc())
+    stmt = select(Sleep).where(Sleep.date >= since_date)
+    if connected_user:
+        stmt = stmt.where(Sleep.user_id == connected_user.polar_user_id)
+    stmt = stmt.order_by(Sleep.date.asc())
     result = await session.execute(stmt)
     sleep_data = result.scalars().all()
 
@@ -1615,12 +1623,20 @@ async def export_activity_csv(
     session: AsyncSession,
     days: int = 30,
 ) -> Response[bytes] | Redirect:
-    """Export activity data as CSV."""
+    """Export activity data as CSV for the connected user."""
     if not is_authenticated(request):
         return Redirect(path="/admin/login", status_code=HTTP_303_SEE_OTHER)
 
+    # Get connected user to filter by user_id
+    connected_user_stmt = select(User).where(User.is_active == True).limit(1)  # noqa: E712
+    connected_user_result = await session.execute(connected_user_stmt)
+    connected_user = connected_user_result.scalar_one_or_none()
+
     since_date = date.today() - timedelta(days=days)
-    stmt = select(Activity).where(Activity.date >= since_date).order_by(Activity.date.asc())
+    stmt = select(Activity).where(Activity.date >= since_date)
+    if connected_user:
+        stmt = stmt.where(Activity.user_id == connected_user.polar_user_id)
+    stmt = stmt.order_by(Activity.date.asc())
     result = await session.execute(stmt)
     activity_data = result.scalars().all()
 
@@ -1655,16 +1671,20 @@ async def export_recharge_csv(
     session: AsyncSession,
     days: int = 30,
 ) -> Response[bytes] | Redirect:
-    """Export recharge/HRV data as CSV."""
+    """Export recharge/HRV data as CSV for the connected user."""
     if not is_authenticated(request):
         return Redirect(path="/admin/login", status_code=HTTP_303_SEE_OTHER)
 
+    # Get connected user to filter by user_id
+    connected_user_stmt = select(User).where(User.is_active == True).limit(1)  # noqa: E712
+    connected_user_result = await session.execute(connected_user_stmt)
+    connected_user = connected_user_result.scalar_one_or_none()
+
     since_date = date.today() - timedelta(days=days)
-    stmt = (
-        select(NightlyRecharge)
-        .where(NightlyRecharge.date >= since_date)
-        .order_by(NightlyRecharge.date.asc())
-    )
+    stmt = select(NightlyRecharge).where(NightlyRecharge.date >= since_date)
+    if connected_user:
+        stmt = stmt.where(NightlyRecharge.user_id == connected_user.polar_user_id)
+    stmt = stmt.order_by(NightlyRecharge.date.asc())
     result = await session.execute(stmt)
     recharge_data = result.scalars().all()
 
@@ -1697,12 +1717,20 @@ async def export_cardio_load_csv(
     session: AsyncSession,
     days: int = 30,
 ) -> Response[bytes] | Redirect:
-    """Export cardio load data as CSV."""
+    """Export cardio load data as CSV for the connected user."""
     if not is_authenticated(request):
         return Redirect(path="/admin/login", status_code=HTTP_303_SEE_OTHER)
 
+    # Get connected user to filter by user_id
+    connected_user_stmt = select(User).where(User.is_active == True).limit(1)  # noqa: E712
+    connected_user_result = await session.execute(connected_user_stmt)
+    connected_user = connected_user_result.scalar_one_or_none()
+
     since_date = date.today() - timedelta(days=days)
-    stmt = select(CardioLoad).where(CardioLoad.date >= since_date).order_by(CardioLoad.date.asc())
+    stmt = select(CardioLoad).where(CardioLoad.date >= since_date)
+    if connected_user:
+        stmt = stmt.where(CardioLoad.user_id == connected_user.polar_user_id)
+    stmt = stmt.order_by(CardioLoad.date.asc())
     result = await session.execute(stmt)
     cardio_data = result.scalars().all()
 

src/polar_flow_server/api/__init__.py

@@ -4,6 +4,7 @@
 
 from polar_flow_server.api.baselines import baselines_router
 from polar_flow_server.api.data import data_router
+from polar_flow_server.api.export import export_router
 from polar_flow_server.api.health import health_router
 from polar_flow_server.api.insights import insights_router
 from polar_flow_server.api.keys import keys_router, oauth_router
@@ -21,6 +22,7 @@
     patterns_router,  # Pattern detection and anomalies
     insights_router,  # Unified insights API
     keys_router,  # Key management (regenerate, revoke, status)
+    export_router,  # CSV data export
 ]
 
 api_v1_router = Router(path="/api/v1", route_handlers=_v1_routers)