Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.saturday.fit/llms.txt

Use this file to discover all available pages before exploring further.

​
Nutrition Calculation

The nutrition calculation endpoint is Saturday’s core product. It takes an activity description and returns a personalized fuel prescription — carbohydrate, hydration, and electrolyte targets — with safety guardrails applied. 
POST /v1/nutrition/calculate

​
Progressive enrichment

Saturday works with whatever data you have. More data produces more accurate prescriptions — but even minimal inputs return useful results.

​
Minimal inputs

The bare minimum for a calculation: 
response = requests.post(
    "https://api.saturday.fit/v1/nutrition/calculate",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "activity_type": "run",
        "duration_min": 90,
        "athlete_weight_kg": 70,
    },
)
This returns a prescription with a low confidence_score. The numbers are based on population-level defaults for the given activity type and body weight.

​
Standard inputs

Add intensity and environmental conditions for a meaningfully better prescription: 
{
  "activity_type": "bike",
  "duration_min": 180,
  "intensity_level": 7,
  "athlete_weight_kg": 68,
  "thermal_stress_level": 8
}
Thermal stress dramatically affects hydration and sodium needs. A 3-hour ride at high thermal stress requires very different fueling than the same ride in cool conditions.

​
Comprehensive inputs

For the highest accuracy, include an athlete reference: 
{
  "activity_type": "bike",
  "duration_min": 300,
  "intensity_level": 8,
  "is_race": true,
  "athlete_id": "ath_abc123",
  "thermal_stress_level": 7
}
When you include an athlete_id, Saturday pulls their stored profile — sweat level, saltiness, carb experience, fitness level, and past activity feedback. This is where prescriptions become genuinely personalized.
The enrichment path: Start with minimal inputs to get integrated fast, then progressively add more data as your integration matures. Every additional field improves accuracy.

​
Understanding the response

{
  "tier": "full",
  "carb_g_per_hr": 72,
  "sodium_mg_per_hr": 800,
  "fluid_ml_per_hr": 750,
  "total_carb_g": 360,
  "total_sodium_mg": 4000,
  "total_fluid_ml": 3750,
  "safety": {
    "max_safe_fluid_ml_per_hr": 1500,
    "max_safe_sodium_mg_per_hr": 3000,
    "confidence_score": 0.85,
    "requires_human_review": false,
    "warnings": [
      "High thermal stress. Consider ice, cold fluids, and shade."
    ],
    "not_instructions": true
  },
  "attribution": {
    "text": "Powered by Saturday",
    "logo_url": "https://saturdaymorning.fit/logo.png",
    "link": "https://saturdaymorning.fit",
    "required": false
  }
}

​
Confidence score

The safety.confidence_score (0.0-1.0) indicates how personalized the prescription is:
RangeMeaningTypical inputs
0.8-1.0Strong personalization, athlete historyAthlete profile + conditions + feedback
0.5-0.8Good estimates with some personalizationWeight + intensity + thermal stress
0.0-0.5Population-level defaults appliedMinimal inputs (type + duration + weight)

​
Comparing scenarios

Compare prescriptions across different conditions — ideal for race-day planning UIs: 
POST /v1/nutrition/calculate/compare

{
  "athlete_id": "ath_abc123",
  "activity_type": "run",
  "duration_min": 240,
  "intensity_level": 8,
  "is_race": true,
  "scenarios": [
    {
      "label": "Cool morning",
      "thermal_stress_level": 3
    },
    {
      "label": "Hot afternoon",
      "thermal_stress_level": 8
    }
  ]
}

​
Teaser vs. full responses

Responses depend on the athlete’s Saturday subscription status:
  • Subscribed athletes get exact numbers: "carb_g_per_hr": 72
  • Free/teaser athletes get ranges: "carb_range_g_per_hr": "55-85"
See Freemium Model for implementation details.

​
Safety

Every calculation response includes a safety block. This is non-negotiable — Saturday is a nutrition API for athletes, and bad recommendations can cause real harm. See Safety for the full guide on safety fields, risk levels, and display requirements.
Safety data is never gated behind subscription status. Even teaser responses include complete safety metadata.

​
Supported activity types

TypeKeyNotes
RunningrunRoad, trail, track
CyclingbikeRoad, gravel, mountain
SwimmingswimPool, open water
RowingrowOn-water, ergometer
SkiingskiCross-country, classic, skate
HikinghikeLong-duration, variable intensity
WeightliftingliftStrength training
Use GET /v1/activity-types for the complete list with descriptions.