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

# Quickstart

> 5 minutes to your first API call

# 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](https://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](/access).

**Platform partners:** keys come with your agreement — contact [api@saturday.fit](mailto:api@saturday.fit). Partner sandbox keys start with `sk_test_` and work against test data with no rate limit concerns.

```
sk_live_abc123def456...
```

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

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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### Install an SDK (optional)

Saturday provides official SDKs for Python and TypeScript:

<CodeGroup>
  ```bash Python theme={null}
  pip install saturday
  ```

  ```bash TypeScript theme={null}
  npm install @saturdayinc/sdk
  ```
</CodeGroup>

<CodeGroup>
  ```python Python (SDK) theme={null}
  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)
  ```

  ```typescript TypeScript (SDK) theme={null}
  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);
  ```
</CodeGroup>

## 3. Read the response

A successful response returns a fuel prescription with safety metadata:

```json theme={null}
{
  "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                 |

<Warning>
  **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.
</Warning>

## 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:

```json theme={null}
{
  "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](/guides/freemium-model) for the full details.

## 5. Next steps

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

<Steps>
  <Step title="Create an athlete profile">
    [Athletes](/guides/athletes) — Store athlete settings (weight, sweat level, preferences) for more accurate calculations.
  </Step>

  <Step title="Understand safety">
    [Safety](/guides/safety) — Learn about Saturday's safety model and why it matters.
  </Step>

  <Step title="Track activities">
    [Activities](/guides/activities) — Create activities, attach prescriptions, and collect feedback.
  </Step>

  <Step title="Go to production">
    [Authentication](/authentication) — Swap your `sk_test_` key for a `sk_live_` key when you're ready.
  </Step>
</Steps>