Sellwyse Backend API Reference¶

Base URL: https://api.sellwyse.com (prod) | http://localhost:9394 (dev)
Auth: Bearer token in Authorization header
Content-Type: application/json

Quick Reference¶

Category	Endpoints	Methods
Auth	`/auth/*`	POST
Health Metrics	`/health/metrics`	CRUD
Body	`/body`	CRUD
Food	`/food`	CRUD
Devices	`/devices`	CRUD
Goals	`/goals/daily/me`	GET, PUT
Exercises	`/exercises/*`	CRUD
Transformations	`/transformations`	CRUD
Leaderboards	`/leaderboards`	GET, POST

1. Health Metrics¶

POST /health/metrics¶

Create a health metric entry.

{
  "metric_type": "daily|recovery|sleep|activity|heart_rate|body_composition",
  "measured_at": "2025-02-04T00:00:00Z",

  // Core Vitals
  "heart_rate_bpm": 72,
  "resting_hr": 60,
  "hrv_ms": 45.5,
  "hrv_rmssd": 42.0,
  "blood_pressure_sys": 120,
  "blood_pressure_dia": 80,
  "spo2_percent": 98.5,
  "body_temp_c": 36.8,
  "respiratory_rate": 16,

  // Activity
  "steps": 10000,
  "distance_m": 7500.0,
  "calories": 500,
  "active_minutes": 60,
  "floors_climbed": 10,

  // Body Composition
  "weight_kg": 75.0,
  "body_fat_percent": 18.0,
  "muscle_mass": 40.0,
  "bmi": 23.5,
  "visceral_fat": 10,
  "water_percentage": 55.0,

  // Sleep
  "sleep_duration_mins": 480,
  "sleep_score": 85,
  "sleep_efficiency": 90,
  "sleep_deep_min": 90,
  "sleep_rem_min": 120,
  "sleep_light_min": 270,
  "sleep_awake_min": 15,

  // Recovery (NEW)
  "muscle_soreness": 3,        // 1-10 scale
  "perceived_fatigue": 4,      // 1-10 scale
  "motivation_level": 8,       // 1-10 scale
  "energy_level": 7,           // 1-10 scale
  "mood_score": 8,             // 1-10 scale
  "stress_level": 3,           // 1-10 scale
  "hydration_status": "Well Hydrated",
  "soreness_locations": ["shoulders", "legs"],

  // Scores
  "readiness_score": 85,
  "strain_score": 12.5,
  "recovery_score": 75
}

Response:

{
  "success": true,
  "data": {
    "id": "01ABC123...",
    "user_id": "...",
    "metric_type": "daily",
    ...all fields...
  }
}

GET /health/metrics¶

List metrics with filters.

Query params: - metric_type - Filter by type - from - Start date (ISO8601) - to - End date (ISO8601) - limit - Max results (default 100) - offset - Pagination offset

GET /health/metrics/{id}¶

Get single metric by ID.

PUT /health/metrics/{id}¶

Update a metric. Send only fields to update.

DELETE /health/metrics/{id}¶

Delete a metric.

2. Body Measurements¶

POST /body¶

{
  "weight_kg": 75.5,
  "height_cm": 178,
  "body_fat_percent": 18.0,
  "muscle_mass_kg": 35.0,
  "bone_mass_kg": 3.2,
  "water_percent": 55.0,
  "visceral_fat": 10,
  "metabolic_age": 28,
  "bmr": 1800
}

GET /body¶

GET /body/{id}¶

PUT /body/{id}¶

DELETE /body/{id}¶

3. Food Log¶

POST /food¶

{
  "name": "Chicken Breast",
  "meal_type": "lunch|breakfast|dinner|snack",
  "calories": 650,
  "protein_g": 45,
  "carbs_g": 20,
  "fat_g": 15,
  "fiber_g": 5,
  "sugar_g": 2,
  "sodium_mg": 500,
  "quantity": 1,
  "unit": "serving"
}

GET /food¶

GET /food/{id}¶

PUT /food/{id}¶

DELETE /food/{id}¶

GET /food/summary - Daily nutrition summary¶

4. Devices¶

POST /devices¶

{
  "name": "Apple Watch Series 9",
  "device_type": "smartwatch|scale|blood_pressure|glucose|fitness_tracker",
  "manufacturer": "Apple",
  "model": "Series 9",
  "serial_number": "ABC123",
  "firmware_version": "10.0"
}

GET /devices¶

GET /devices/{id}¶

PUT /devices/{id} - Update connection status, battery, etc.¶

DELETE /devices/{id}¶

5. Daily Goals¶

GET /goals/daily/me¶

Get user's daily goals.

Response:

{
  "success": true,
  "data": {
    "daily_steps_goal": 10000,
    "daily_calories_goal": 2500,
    "daily_distance_meters": 8000,
    "daily_active_minutes_goal": 60,
    "daily_water_ml_goal": 2500,
    "daily_sleep_minutes_goal": 480
  }
}

PUT /goals/daily/me¶

{
  "daily_steps_goal": 12000,
  "daily_calories_goal": 2200,
  "walk_goal": {
    "type": "steps",
    "daily_steps_goal": 12000
  }
}

6. Exercises¶

GET /exercises/types¶

List all exercise types (Walking, Running, Weight Lifting, etc.)

POST /exercises/sessions¶

{
  "exercise_type_id": "01JKC001EXERC1SEWALKING",
  "started_at": "2025-02-04T10:00:00Z",
  "ended_at": "2025-02-04T10:45:00Z",
  "duration_mins": 45,
  "calories_burned": 300,
  "distance_m": 5000,
  "avg_heart_rate": 130,
  "max_heart_rate": 155,
  "sets": [
    {"reps": 10, "weight_kg": 50},
    {"reps": 8, "weight_kg": 55}
  ]
}

GET /exercises/sessions¶

GET /exercises/sessions/{id}¶

PUT /exercises/sessions/{id}¶

DELETE /exercises/sessions/{id}¶

7. Transformations (NEW)¶

Track body transformations with before/after photos and measurements.

POST /transformations¶

{
  "title": "Summer Body 2025",
  "description": "Get beach ready",
  "date_started": "2025-01-01",
  "target_date": "2025-06-01",
  "weight_before": 85.5,
  "body_fat_before": 25.0,
  "weight_goal": 75.0,
  "body_fat_goal": 15.0,
  "visibility": "private|friends|public"
}

GET /transformations¶

List user's transformations.

GET /transformations/{id}¶

Get transformation with measurements and milestones.

PUT /transformations/{id}¶

Update transformation details.

DELETE /transformations/{id}¶

POST /transformations/{id}/measurements¶

Add progress measurement.

{
  "measured_at": "2025-02-01",
  "weight_kg": 82.0,
  "body_fat_percent": 22.0,
  "photo_front_url": "https://...",
  "photo_side_url": "https://...",
  "circ_waist": 88.0,
  "circ_chest": 100.0,
  "circ_arms": 35.0,
  "circ_thighs": 55.0
}

POST /transformations/{id}/milestones¶

Add milestone.

{
  "milestone_type": "weight_loss|body_fat|strength|custom",
  "title": "First 5kg lost",
  "target_value": 5.0,
  "achieved_at": null
}

PUT /transformations/{id}/milestones/{milestone_id}¶

Mark milestone as achieved.

8. Leaderboards (NEW)¶

Compete with friends on fitness metrics.

GET /leaderboards¶

List available leaderboards.

Response:

{
  "success": true,
  "data": {
    "leaderboards": [
      {
        "id": "01LEADER001STEPS00",
        "name": "Weekly Steps Challenge",
        "leaderboard_type": "steps",
        "period_type": "weekly",
        "is_active": true
      }
    ]
  }
}

GET /leaderboards/{id}¶

Get leaderboard with rankings.

Response:

{
  "success": true,
  "data": {
    "leaderboard": {...},
    "rankings": [
      {
        "rank": 1,
        "user_id": "...",
        "display_name": "John D.",
        "steps_total": 85000,
        "calories_total": 3500
      }
    ],
    "user_entry": {
      "rank": 5,
      "steps_total": 45000
    }
  }
}

POST /leaderboards/{id}/join¶

Join a leaderboard.

POST /leaderboards/{id}/leave¶

Leave a leaderboard.

POST /leaderboards/{id}/score¶

Submit score update (called automatically when metrics are logged).

Error Responses¶

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field value",
    "details": {...}
  }
}

Common error codes: - 400 - Bad Request / Validation Error - 401 - Unauthorized (missing/invalid token) - 403 - Forbidden (no permission) - 404 - Not Found - 500 - Internal Server Error

Rate Limits¶

100 requests/minute per user
1000 requests/hour per user
Bulk endpoints: 10 requests/minute

Metrics Coverage¶

Category	Count	Status
Vitals & Biometrics	27	✅
Body Composition	20	✅
Strength & Power	15	✅
Sleep	10	✅
Nutrition	12	✅
Workout & Training	25	✅
Recovery & Readiness	18	✅
Transformation	20	✅
Leaderboard	10	✅
DNA & Genetics	6	✅
Calculated Scores	15	✅
Device/Integration	10	✅
User Patterns	12	✅
TOTAL	200	✅ 100%