Skip to content

quickstart.mdx

Latest commit

 

History

History
234 lines (186 loc) · 6.34 KB

quickstart.mdx

File metadata and controls

234 lines (186 loc) · 6.34 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

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:

[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.