Skip to content

quickstart.mdx

Latest commit

 

History

History
232 lines (185 loc) · 5.99 KB

quickstart.mdx

File metadata and controls

232 lines (185 loc) · 5.99 KB
title Quickstart
description 5 minutes to your first API call
sidebarTitle Quickstart

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
  }'
import requests

response = requests.post(
    "https://api.saturday.fit/v1/nutrition/calculate",
    headers={
        "Authorization": "Bearer sk_test_abc123def456",
        "Content-Type": "application/json",
    },
    json={
        "activity_type": "run",
        "duration_min": 90,
        "intensity_level": 5,
        "athlete_weight_kg": 70,
        "thermal_stress_level": 6,
    },
)

data = response.json()
print(data)
const response = await fetch(
  "https://api.saturday.fit/v1/nutrition/calculate",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_type: "run",
      duration_min: 90,
      intensity_level: 5,
      athlete_weight_kg: 70,
      thermal_stress_level: 6,
    }),
  }
);

const data = await response.json();
console.log(data);

Install an SDK (optional)

Saturday provides official SDKs for Python and TypeScript:

pip install saturday
npm install @saturdayinc/sdk
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)
import Saturday from "@saturdayinc/sdk";

const client = new Saturday({ apiKey: "sk_test_abc123def456" });

const result = await client.nutrition.calculate({
  activityType: "run",
  durationMin: 90,
  intensityLevel: 5,
  athleteWeightKg: 70,
  thermalStressLevel: 6,
});

console.log(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:

Field What it means
tier Response tier — "full" for subscribed athletes, "teaser" for free
carb_g_per_hr Carbohydrate target in grams per hour
sodium_mg_per_hr Sodium target in milligrams per hour
fluid_ml_per_hr Fluid target in milliliters per hour
total_* Total amounts for the entire activity duration
safety.confidence_score How confident Saturday is in this prescription (0.0-1.0)
safety.warnings Any safety warnings for this prescription
safety.not_instructions Signals 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 status What they get Example
Subscribed Exact numbers "carb_g_per_hr": 62.5
Free / teaser Ranges "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:

[Athletes](/guides/athletes) — Store athlete settings (weight, sweat level, preferences) for more accurate calculations. [Safety](/guides/safety) — Learn about Saturday's safety model and why it matters. [Activities](/guides/activities) — Create activities, attach prescriptions, and collect feedback. [Authentication](/authentication) — Swap your `sk_test_` key for a `sk_live_` key when you're ready.