Quickstart

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

1. Get your API key

Self-serve (most builders): sign up at saturday.fit/api — $5.39/month, no contract. Your key is revealed once after checkout and emailed to you. An AI agent can do this for you too: POST /v1/signup (no auth) returns a hosted checkout link. Not sure self-serve is your lane? See Getting Access. Platform partners: keys come with your agreement — contact api@saturday.fit. Partner sandbox keys start with sk_test_ and work against test data with no rate limit concerns.

sk_live_abc123def456...

Treat your key like a password — it authenticates every request and spends your daily call allowance.

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({
  activity_type: "run",
  duration_min: 90,
  intensity_level: 5,
  athlete_weight_kg: 70,
  thermal_stress_level: 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://saturday.fit/logo.png",
    "link": "https://saturday.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:

Create an athlete profile

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

Understand safety

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

Track activities

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

Go to production

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

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Quickstart

Quickstart

1. Get your API key

2. Make your first calculation

Install an SDK (optional)

3. Read the response

4. Understand teaser vs. full responses

5. Next steps

​Quickstart

​1. Get your API key

​2. Make your first calculation

​Install an SDK (optional)

​3. Read the response

​4. Understand teaser vs. full responses

​5. Next steps

Quickstart

1. Get your API key

2. Make your first calculation

Install an SDK (optional)

3. Read the response

4. Understand teaser vs. full responses

5. Next steps