Fitness Dashboard — Agent Documentation

Complete guide for AI agents operating Sandy's fitness tracking system. This documentation covers the training philosophy, available data, API operations, and recommended workflows.

Training Philosophy

Sandy trains with a four-vector model. Every workout must contribute to at least one vector. These vectors are fixed — do not invent new ones.

Movement Planes

Every exercise maps to exactly one movement plane:

• Push — Horizontal pushing (push-ups, bench press)
• Pull — Horizontal pulling (rows, pull-ups)
• Press — Vertical pushing (overhead press, lateral raises)
• Hinge — Hip hinge (swings, deadlifts, cleans, get-ups)
• Squat — Bilateral squat pattern (goblet squats)
• SideSquat — Unilateral/lateral squat (cossacks, side lunges)
• Twist — Rotational/anti-rotational (windmills, Turkish get-ups)
• Run — Locomotion (sprints, running)

Authentication

Every API call requires authentication. Prefer JWT tokens via the Authorization: Bearer <token> header. Legacy API key fallback uses X-API-Key.

Base URLs

• Production: https://fitness-dashboard.netlify.app/api
• Local Dev: http://localhost:8888/api

How Agents Should Operate

Core Principles

1. Read before writing — Always check existing data (goals, recent workouts, equipment) before making recommendations
2. Respect the four vectors — Every workout design must address at least one vector
3. Use correct movement planes — Never invent new planes; use the 8 defined ones
4. Work within equipment constraints — Only recommend exercises with available equipment
5. Track progress toward goals — Reference active goals when giving advice

Designing a Workout

Logging a Completed Workout

Context Sources

Agents have access to the following data sources to inform decisions:

Common Workflows

1. Design Next Workout

// Step 1: Get context
GET /goals?status=Active
GET /equipment
GET /workouts?limit=5&status=analysed
GET /analytics/summary

// Step 2: Analyze gaps
- Which goals are behind?
- Which planes haven't been trained recently?
- What equipment is available?

// Step 3: Design workout
POST /workouts
{
  "date": "2026-04-23",
  "type": "KB",
  "status": "planned",
  "title": "KB Push/Pull Focus",
  "intensity": "Moderate",
  "exercises": [...]
}

2. Log Completed Workout

// Step 1: Create workout entry
POST /workouts
{
  "date": "2026-04-23",
  "type": "KB",
  "status": "logged",
  "duration_minutes": 35,
  "intensity": "Hard",
  "notes": "User raw input: '8:15 start. 5x10 double cleans @ 12kg...'"
}

// Step 2: Add exercises
POST /exercises (for each exercise)
{
  "workout_id": "w_xxx",
  "name": "Double KB Cleans",
  "movement_plane": "Hinge",
  "actual_sets": 5,
  "actual_reps": 10,
  "actual_weight_kg": 24,
  "volume_kg": 1200,
  "status": "completed"
}

// Step 3: Upload photo to Netlify Blobs
POST /api/blobs/upload
{ "data": "base64encodedstring...", "content_type": "image/jpeg" }

// Step 4: Attach blob key to workout
PUT /workouts/w_xxx
{ "photo_key": "blob_xxx..." }

// Step 5: Mark complete
PUT /workouts/w_xxx
{ "status": "analysed" }

3. Generate Periodic Analysis

// Step 1: Get recent completed workouts
GET /workouts?status=analysed&date_from=2026-04-01

// Step 2: Analyze patterns
- Volume trends
- Plane coverage
- Goal progress
- Strength/efficiency changes

// Step 3: Store meta-analysis
POST /analysis-cycles
{
  "start_date": "2026-04-01",
  "end_date": "2026-04-21",
  "workouts_analyzed": 12,
  "summary": "Weekly analysis...",
  "recommendations": "Next week focus on..."
}

API Overview

The REST API follows standard patterns with JSON request/response bodies. All endpoints require authentication.

Response Format

{
  "data": [...],      // Array of results
  "total": 42,        // Total count (for pagination)
  "limit": 20,        // Page size
  "offset": 0         // Current offset
}

Error Format

{
  "error": "NotFound",
  "message": "Workout not found"
}

Workouts API

Query Parameters

• type — Filter by workout type (KB, GYM, PB, Yoga, Other)
• status — Filter by status (planned, logged, analysed). Comma-separated for multiple.
• date_from — Start date (YYYY-MM-DD)
• date_to — End date (YYYY-MM-DD)
• limit — Page size (default 20)
• offset — Pagination offset

Workout Statuses

• planned — Future workout, not yet performed
• logged — Completed but awaiting analysis
• analysed — Fully processed and counted

Exercises API

Exercises are always linked to a workout. They represent individual movements with volume tracking.

Exercise Fields

• name — Exercise name (e.g., "Double KB Cleans")
• movement_plane — One of: Push, Pull, Press, Hinge, Squat, SideSquat, Twist, Run
• planned_sets/reps/weight — Targets for the exercise
• actual_sets/reps/weight — What was actually done
• volume_kg — Calculated: sets × reps × weight
• status — completed, modified, skipped

Equipment API

Inventory of available fitness equipment. Used by agents to design feasible workouts.

Categories

• KB — Kettlebells
• DB — Dumbbells
• Barbell — Barbells and plates
• Machine — Weight machines
• Other — Miscellaneous equipment

Goals API

Goal tracking organized by training vector and optional movement plane.

Goal Vectors

• Strength — Peak load targets
• Endurance — Total volume targets
• Efficiency — kg/min targets
• Mobility — Range/quality targets

Goal Statuses

• Active — Currently pursuing
• Achieved — Target reached
• Paused — Temporarily suspended
• Abandoned — No longer pursuing

Analytics API

Aggregate statistics for tracking progress across vectors and movement planes.

GET /analytics/summary

Returns aggregate metrics. Optionally filter by date range with date_from and date_to query params.

{
  "total_workouts": 42,
  "total_volume_kg": 45000,
  "avg_efficiency": 145.5,
  "by_type": { "KB": 35, "GYM": 7 },
  "by_vector": {
    "Strength": { "peak_load_kg": 60, "exercises": 120 },
    "Endurance": { "total_volume_kg": 45000 },
    "Efficiency": { "avg_kg_per_min": 145.5 },
    "Mobility": { "sessions_count": 42 }
  },
  "by_movement_plane": {
    "Hinge": { "total_volume": 15000, "peak_load": 60 },
    "Press": { "total_volume": 8000, "peak_load": 32 }
  }
}

Data Model Reference

Workouts Table

Exercises Table

Statuses & Enums

Photo Upload

Photos are uploaded via Netlify Blobs. The frontend uploads the file to POST /api/blobs/upload, which returns a blob key. The photo_url field on the workout stores this key.

To display a photo, use GET /api/blobs/<key>. Agents should use the blob endpoints rather than storing base64 data in the database.

Workout Status Lifecycle

planned → logged → analysed

• planned — Workout designed but not yet performed. Shows in "Next Workout" box.
• logged — Workout completed but data not fully processed. Not counted in analytics.
• analysed — Fully processed workout. Counted in all statistics and analytics.

Exercise Status

• completed — Done as planned
• modified — Changed during workout (different reps/weight)
• skipped — Not performed

Workout Types

• KB — Kettlebell training
• GYM — Gym/machine work
• PB — Plyo/box work
• Yoga — Yoga session
• Other — Miscellaneous