SneakySwole/docs/API_REFERENCE.md

# API Reference

All endpoints return HTML (full pages or HTMX partials) unless noted otherwise. Protected routes require a valid admin session cookie.

---

## Authentication

### `GET /login`

Render the login form.

- **Auth:** None
- **Response:** Full page (`pages/login.html`)

### `POST /login`

Authenticate admin credentials and start a session.

- **Auth:** None
- **Content-Type:** `application/x-www-form-urlencoded`
- **Form fields:**
  - `username` (string) — admin username
  - `password` (string) — admin password
- **Success:** 303 redirect to `/`, sets `session` cookie (httponly, samesite=lax, 24h TTL)
- **Failure:** 200 with login page re-rendered and error message

### `GET /logout`

End the admin session.

- **Auth:** None (clears cookies regardless)
- **Response:** 303 redirect to `/login`, deletes `session` and `active_profile_id` cookies

---

## Health

### `GET /health`

Application health check for monitoring and readiness probes.

- **Auth:** None
- **Response:** JSON
  ```json
  {
    "app": "sneakyswole",
    "version": "0.1.0",
    "status": "ok"
  }
  ```

---

## Pages

### `GET /`

Home page.

- **Auth:** None
- **Response:** Full page (`pages/home.html`)

---

## Profiles

All profile routes require admin authentication.

### `GET /profiles`

List all user profiles (excludes admin).

- **Auth:** Admin session
- **Response:** Full page (`pages/profiles.html`)
- **Template context:** `profiles`, `active_profile_id`, `admin`

### `POST /profiles/switch`

Switch the active user profile.

- **Auth:** Admin session
- **Content-Type:** `application/x-www-form-urlencoded`
- **Form fields:**
  - `profile_id` (string) — ID of the profile to activate
- **Response:** 303 redirect to referring page, sets `active_profile_id` cookie

### `GET /profiles/{profile_id}/edit`

Render the profile edit form.

- **Auth:** Admin session
- **Path params:** `profile_id` (int)
- **Response:** Full page (`pages/profile_edit.html`)

### `POST /profiles/{profile_id}/edit`

Update a user profile.

- **Auth:** Admin session
- **Path params:** `profile_id` (int)
- **Content-Type:** `application/x-www-form-urlencoded`
- **Form fields:**
  - `display_name` (string)
  - `height` (string)
  - `weight` (string)
  - `goals` (string)
- **Response:** 303 redirect to `/profiles`

---

## Workouts

All workout routes require admin authentication.

### `GET /workouts`

List all workout days as clickable cards.

- **Auth:** Admin session
- **Response:** Full page (`pages/workout_days.html`)
- **Template context:** `days`, `admin`

### `GET /workouts/{day_name}`

Display a full workout day with warmups, exercises, programming targets, and inline logging.

- **Auth:** Admin session
- **Path params:** `day_name` (string) — URL-friendly name, e.g., "push", "pull", "lower", "full-body"
- **Response:** Full page (`pages/workout_day.html`)
- **Template context:** `day_name`, `warmups`, `exercises`, `programs`, `active_profile`, `existing_logs`, `suggestions`, `workout_day_id`, `admin`
- **Notes:** Day name is normalized (e.g., "full-body" → "Full Body"). If an active profile is set, includes programming targets, progression suggestions, and today's existing logs.

---

## Exercises

All exercise routes require admin authentication.

### `GET /exercises`

Render the exercise browser with filter dropdowns.

- **Auth:** Admin session
- **Response:** Full page (`pages/exercise_browser.html`)
- **Template context:** `exercises`, `workout_days`, `muscle_groups`, `admin`

### `GET /exercises/search`

HTMX partial — return filtered exercise list.

- **Auth:** Admin session
- **Query params:**
  - `workout_day` (string, optional) — filter by workout day name
  - `muscle_group` (string, optional) — filter by muscle group
- **Response:** HTMX partial (`partials/exercise_list.html`)
- **Usage:** Called via `hx-get` from exercise browser filter dropdowns

---

## Workout Logging

All logging routes require admin authentication. Responses are HTMX partials that update inline.

### `POST /log`

Log a single set for an exercise. Auto-creates today's workout session if needed.

- **Auth:** Admin session
- **Content-Type:** `application/x-www-form-urlencoded`
- **Form fields:**
  - `exercise_id` (int)
  - `workout_day_id` (int)
  - `set_number` (int, default=1)
  - `reps` (int)
  - `weight` (string) — e.g., "30 lbs", "BW"
  - `felt_easy` (checkbox, "on" = true)
- **Response:** HTMX partial (`partials/log_entry.html`) with updated logs for this exercise
- **Error:** If no active profile selected, returns `partials/flash_message.html` with error

### `POST /log/{log_id}/edit`

Edit an existing log entry.

- **Auth:** Admin session
- **Path params:** `log_id` (int)
- **Content-Type:** `application/x-www-form-urlencoded`
- **Form fields:**
  - `reps` (int)
  - `weight` (string)
  - `felt_easy` (checkbox)
  - `notes` (string, optional)
- **Response:** HTMX partial (`partials/log_entry.html`) with updated logs

### `POST /log/{log_id}/delete`

Delete a log entry.

- **Auth:** Admin session
- **Path params:** `log_id` (int)
- **Response:** HTMX partial (`partials/log_entry.html`) with remaining logs, or empty HTML if log not found

---

## History

All history routes require admin authentication.

### `GET /history`

Display log history for the active profile — list of past sessions, most recent first.

- **Auth:** Admin session
- **Response:** Full page (`pages/log_history.html`)
- **Template context:** `sessions`, `days_by_id`, `active_profile`, `admin`
- **Notes:** Requires active profile to show sessions

### `GET /history/{session_id}`

Display detailed logs for a specific workout session, grouped by exercise.

- **Auth:** Admin session
- **Path params:** `session_id` (int)
- **Response:** Full page (`pages/session_detail.html`)
- **Template context:** `workout_session`, `logs_by_exercise`, `exercises_by_id`, `days_by_id`, `admin`

---

## Dashboard

All dashboard routes require admin authentication.

### `GET /dashboard`

Render the progress dashboard with summary stats, volume chart, and exercise links.

- **Auth:** Admin session
- **Response:** Full page (`pages/dashboard.html`)
- **Template context:** `stats`, `volume_data_json`, `exercises`, `active_profile`, `admin`
- **Notes:** Stats and volume data require an active profile. Chart.js renders client-side charts from JSON embedded in the template.

### `GET /dashboard/exercise/{exercise_id}`

Per-exercise progress page with charts and progression suggestions.

- **Auth:** Admin session
- **Path params:** `exercise_id` (int)
- **Response:** Full page (`pages/exercise_progress.html`)
- **Template context:** `exercise`, `progress_data_json`, `suggestion`, `active_profile`, `admin`

---

## Schedule

### `GET /schedule`

4-week calendar view showing which workout day maps to which date.

- **Auth:** Admin session
- **Response:** Full page (`pages/schedule.html`)
- **Template context:** `weeks`, `active_profile`, `admin`
- **Notes:** Calendar starts from Monday of the current week. Days with completed sessions are highlighted. Requires active profile for session completion data.

---

## Authentication Details

### Cookies

| Cookie | Purpose | Flags | TTL |
|--------|---------|-------|-----|
| `session` | Admin session token (itsdangerous signed) | httponly, samesite=lax | 24 hours |
| `active_profile_id` | Currently selected user profile ID | httponly, samesite=lax | 24 hours |

### Auth Failure Behavior

- Missing or invalid session cookie → 302 redirect to `/login`
- Handled via `NotAuthenticatedError` exception + registered handler in `app/main.py`