Skip to main content

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.

​
Safety

Saturday is a nutrition API for endurance athletes. Bad nutrition advice can cause real harm — and in extreme cases, death. This page explains Saturday’s safety model, why it exists, and what it means for your integration.
This is not a compliance formality. Exercise-associated hyponatremia (EAH) has killed athletes at the Boston Marathon, London Marathon, Marine Corps Marathon, and multiple Ironman races. It happens when athletes overdrink and dilute their blood sodium to dangerous levels. Saturday’s safety guardrails exist to prevent this.

​
What can go wrong

ConditionCauseConsequence
HyponatremiaOverdrinking, insufficient sodiumConfusion, seizures, coma, death
Heat strokeUnder-hydrating in heatOrgan failure, death
GI distressToo many carbs too fastVomiting, cramping, DNF
BonkingInsufficient carbohydrateCollapse, dangerous judgment impairment
RhabdomyolysisExtreme exertion without fuelKidney failure
Saturday’s engine has physiological guardrails for all of these. Every prescription respects hard limits that the algorithm enforces regardless of inputs.

​
The safety block

Every nutrition calculation response — including teasers and free responses — includes a safety object: 
{
  "safety": {
    "max_safe_fluid_ml_per_hr": 1500,
    "max_safe_sodium_mg_per_hr": 3000,
    "confidence_score": 0.72,
    "requires_human_review": false,
    "warnings": [
      "High thermal stress increases dehydration risk. Plan extra fluid access points.",
      "Activities over 4 hours require careful sodium management. Monitor for signs of hyponatremia."
    ],
    "not_instructions": true
  }
}
Safety data is NEVER gated behind subscription status. A teaser response may show carb ranges instead of exact numbers, but it will always show the full safety block with all warnings, confidence scores, and safe maximums. This is non-negotiable.

​
Engine hard limits

Saturday enforces absolute physiological boundaries that cannot be overridden by any input combination:
GuardrailExposed asWhy
Fluid physiological limitmax_safe_fluid_ml_per_hrOverdrinking causes hyponatremia
Sodium ceilingmax_safe_sodium_mg_per_hrExcess sodium causes GI distress and nausea
Minimum sodium(enforced internally)Prevents hyponatremia in extended efforts
Carb gut tolerance(enforced internally)Exceeding gut capacity causes vomiting
Duration scaling(enforced internally)Steady-state assumptions break after 4+ hours
Eating disorder guardrails(enforced internally)Protects vulnerable athletes
These guardrails are evaluated on every calculation. The max_safe_fluid_ml_per_hr and max_safe_sodium_mg_per_hr fields expose the hard ceilings so partners can display them. All other guardrails are enforced internally — prescriptions always respect them.

​
Confidence score and human review

The confidence_score (0.0-1.0) indicates how well-supported the prescription is. When requires_human_review is true, conditions are unusual enough that a human should verify the prescription before following it.
Confidence rangeMeaningYour display recommendation
0.8-1.0Strong personalization, well-understood conditionsNo special display needed
0.5-0.8Good estimates, some assumptions madeShow any warnings in your UI
0.0-0.5Significant uncertainty or risk factorsProminent warning, consider a confirmation step

​
Dangerous vs. safe prescription example

Dangerous (what a naive algorithm might produce for a 4-hour marathon in 30C heat): 
Fluid: 1200 mL/hr
Sodium: 200 mg/hr
Carbs: 120 g/hr
This is dangerous because:
  • 1200 mL/hr exceeds gastric emptying rate — athlete will drink it but not absorb it, diluting blood sodium
  • 200 mg/hr sodium is far too low for hot conditions — hyponatremia risk is extreme
  • 120 g/hr carbs without trained gut tolerance — GI distress guaranteed
Safe (what Saturday produces for the same conditions): 
fluid_ml_per_hr: 700 (capped by physiological limit)
sodium_mg_per_hr: 800 (elevated for salty sweater in heat)
carb_g_per_hr: 72 (limited by demonstrated tolerance)

safety.max_safe_fluid_ml_per_hr: 1500
safety.max_safe_sodium_mg_per_hr: 3000
safety.confidence_score: 0.45
safety.requires_human_review: true
safety.warnings: ["High thermal stress. Plan extra fluid access points and shade."]
safety.not_instructions: true
The difference between these two prescriptions is potentially life-or-death. Saturday’s guardrails ensure the second version is what athletes receive.

​
The not_instructions field

For AI agents consuming Saturday’s API (AI-to-AI communication), responses include: 
{
  "not_instructions": true
}
This field tells AI consumers that Saturday’s prescription data is informational nutrition guidance, not executable instructions. An AI agent should present this data to users for their consideration — not autonomously act on it (e.g., by automatically ordering supplements or modifying an athlete’s plan without consent).

​
Display requirements for partners

​
Required

  • Always show safety warnings when warnings are present or requires_human_review is true
  • Never hide safety data behind expandable sections or “advanced” toggles
  • Never strip safety metadata from responses before displaying to users
  • Include the disclaimer that prescriptions are guidance, not medical advice
  • Show warnings before or alongside the prescription numbers, not hidden in details
  • Use visual hierarchy (color, icons, positioning) to make warnings visible
  • When requires_human_review is true, consider requiring user acknowledgment before proceeding

​
Prohibited

  • Don’t filter warnings based on your own risk assessment
  • Don’t apply your own safety logic on top of Saturday’s — this creates conflicting advice
  • Don’t present prescriptions without any safety context
  • Don’t use Saturday’s numbers as automated triggers (e.g., auto-ordering hydration packs)

​
Contraindications

In rare cases, Saturday may flag a contraindication — a reason the calculation should be treated with extreme caution: 
{
  "contraindications": [
    {
      "code": "extreme_heat_advisory",
      "message": "Calculated conditions exceed safe exercise thresholds. Consult a physician before proceeding.",
      "severity": "critical"
    }
  ]
}
Contraindications are rare and serious. If present, display them prominently and consider blocking the activity plan until the athlete explicitly acknowledges the risk.

​
Eating disorder sensitivity

When an athlete has the eating_disorder_flag set, Saturday:
  • Avoids calorie-focused language
  • Removes weight/restriction framing from rationale text
  • Applies conservative minimums (never under-fuels)
  • Adjusts AI coaching conversation tone
This flag is a backend safety signal. Never expose it in partner UIs. Partners set it based on their own knowledge of the athlete — Saturday uses it to protect that athlete across all interactions.