Skip to main content

​
Quickstart

This guide gets you from zero to a working nutrition calculation in under 5 minutes.

​
1. Get your API key

Contact api@saturday.fit to request a sandbox API key. Sandbox keys start with sk_test_ and work against test data with no rate limit concerns. 
sk_test_abc123def456...
Sandbox keys return realistic data but never affect production athletes. Use them freely during development.

​
2. Make your first calculation

The core of Saturday’s API is the nutrition calculation endpoint. It takes activity parameters and returns a fuel prescription. 
curl -X POST https://api.saturday.fit/v1/nutrition/calculate \
  -H "Authorization: Bearer sk_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "run",
    "duration_min": 90,
    "intensity_level": 5,
    "athlete_weight_kg": 70,
    "thermal_stress_level": 6
  }'

​
Install an SDK (optional)

Saturday provides official SDKs for Python and TypeScript: 
pip install saturday

from saturday import Saturday

client = Saturday(api_key="sk_test_abc123def456")

result = client.nutrition.calculate(
    activity_type="run",
    duration_min=90,
    intensity_level=5,
    athlete_weight_kg=70,
    thermal_stress_level=6,
)

print(result)

​
3. Read the response

A successful response returns a fuel prescription with safety metadata: 
{
  "tier": "full",
  "carb_g_per_hr": 62.5,
  "sodium_mg_per_hr": 485.0,
  "fluid_ml_per_hr": 620.0,
  "total_carb_g": 125,
  "total_sodium_mg": 970,
  "total_fluid_ml": 1240,
  "safety": {
    "max_safe_fluid_ml_per_hr": 1500,
    "max_safe_sodium_mg_per_hr": 3000,
    "confidence_score": 0.72,
    "requires_human_review": false,
    "warnings": [],
    "not_instructions": true
  },
  "attribution": {
    "text": "Powered by Saturday",
    "logo_url": "https://saturdaymorning.fit/logo.png",
    "link": "https://saturdaymorning.fit",
    "required": false
  }
}
Key fields to understand:
FieldWhat it means
tierResponse tier — "full" for subscribed athletes, "teaser" for free
carb_g_per_hrCarbohydrate target in grams per hour
sodium_mg_per_hrSodium target in milligrams per hour
fluid_ml_per_hrFluid target in milliliters per hour
total_*Total amounts for the entire activity duration
safety.confidence_scoreHow confident Saturday is in this prescription (0.0-1.0)
safety.warningsAny safety warnings for this prescription
safety.not_instructionsSignals that prescriptions are guidance, not commands
Safety data is never gated. Every response includes full safety metadata regardless of subscription status. Bad hydration can cause hyponatremia — a potentially fatal condition. Safety information is always free and complete.

​
4. Understand teaser vs. full responses

The response above shows full precision numbers because it’s from a sandbox key. In production, responses depend on the athlete’s subscription status:
Athlete statusWhat they getExample
SubscribedExact numbers"carb_g_per_hr": 62.5
Free / teaserRanges"carb_range_g_per_hr": "60-80"
Teaser responses include a subscription_cta field: 
{
  "tier": "teaser",
  "carb_range_g_per_hr": "60-80",
  "sodium_range_mg_per_hr": "300-600",
  "fluid_range_ml_per_hr": "600-900",
  "subscription_cta": {
    "message": "Subscribe to Saturday for exact fueling targets",
    "subscribe_url": "https://saturday.fit/subscribe?ref=YOUR_PARTNER_ID",
    "features": ["Exact carb/sodium/fluid targets", "Product recommendations"]
  }
}
See Freemium Model for the full details.

​
5. Next steps

You’ve just calculated a nutrition prescription with minimal inputs. From here:
1

Create an athlete profile

Athletes — Store athlete settings (weight, sweat level, preferences) for more accurate calculations.
2

Understand safety

Safety — Learn about Saturday’s safety model and why it matters.
3

Track activities

Activities — Create activities, attach prescriptions, and collect feedback.
4

Go to production

Authentication — Swap your sk_test_ key for a sk_live_ key when you’re ready.