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.

​
Activities

Activities represent individual training sessions or races. Each activity belongs to an athlete and can have a nutrition prescription, selected products, and post-activity feedback attached.

​
Activity lifecycle

Create activity -> Calculate prescription -> (Optional) Add products -> (Optional) Submit feedback
  1. Create the activity with type, duration, and optional intensity/thermal stress
  2. Calculate a nutrition prescription for it
  3. Add products the athlete plans to use (optional — for preparation planning)
  4. Submit feedback after the activity (optional — improves future prescriptions)

​
Creating an activity

import requests

response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "type": "run",
        "name": "Saturday long run",
        "duration_min": 120,
        "intensity_level": 5,
        "scheduled_at": "2025-01-15T07:00:00Z",
        "thermal_stress_level": 4,
    },
)

activity = response.json()
print(f"Activity ID: {activity['id']}")

​
Activity fields

FieldTypeRequiredDescription
typestringYesActivity type (see supported types)
duration_minintegerYesExpected duration in minutes
intensity_levelintegerNo1-9 scale
thermal_stress_levelintegerNo1-9 scale
is_race_eventbooleanNoWhether this is a race
namestringNoHuman-readable label
scheduled_atstringNoISO 8601 datetime

​
Multi-sport activities

For triathlons and brick workouts, specify sub-activities: 
{
  "type": "bike",
  "name": "Olympic distance race",
  "duration_min": 165,
  "intensity_level": 8,
  "is_race_event": true
}
Saturday calculates prescriptions tailored to the activity type — you fuel differently on the bike than on a run.

​
Calculating a prescription

POST /v1/athletes/{athlete_id}/activities/{activity_id}/prescription
This uses the activity’s parameters and the athlete’s profile to generate a personalized prescription. Recalculating overwrites the previous prescription — use this when activity parameters change (e.g., updated weather forecast). The response is the prescription object itself (carb/sodium/fluid values, totals, per-hour rates).

​
Getting a stored prescription

GET /v1/athletes/{athlete_id}/activities/{activity_id}/prescription
Returns the most recently calculated prescription for this activity, wrapped with safety metadata: 
{
  "prescription": {
    "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,
    "calculated_at": "2025-01-15T06:55:00Z"
  },
  "safety": {
    "max_safe_fluid_ml_per_hr": 1801,
    "max_safe_sodium_mg_per_hr": 5000,
    "confidence_score": 0.85,
    "not_instructions": true,
    "warnings": []
  }
}
The {prescription, safety} envelope is consistent across all Saturday endpoints that return prescription data. Always read prescription.* for values and safety.* for guardrail information. The not_instructions: true flag signals that these are recommendations for human consideration, not executable commands.

​
Getting an activity with prescription

GET /v1/athletes/{athlete_id}/activities/{activity_id}
The activity response includes the prescription inline, along with any attached products.

​
Listing activities

GET /v1/athletes/{athlete_id}/activities?from=2025-01-01&to=2025-01-31&type=running
Supports filtering by date range and type.

​
Submitting feedback

Post-activity feedback improves future prescriptions: 
response = requests.post(
    "https://api.saturday.fit/v1/athletes/ath_abc123/activities/act_xyz789/feedback",
    headers={"Authorization": "Bearer sk_test_abc123def456"},
    json={
        "gi_comfort": "good",
        "energy_level": "adequate",
        "hydration_feel": "slightly_dehydrated",
        "notes": "Felt good until mile 18, then energy dropped",
        "actual_intake": {
            "carbs_grams": 100,
            "fluid_ml": 900,
            "sodium_mg": 800,
        },
    },
)

​
Feedback fields

FieldValuesDescription
gi_comfortexcellent, good, fair, poorGI comfort during activity
energy_levelsurplus, adequate, low, bonkedEnergy levels throughout
hydration_feelover_hydrated, well_hydrated, slightly_dehydrated, dehydratedPerceived hydration
actual_intakeobjectWhat the athlete actually consumed
Feedback is the single most valuable signal for improving future prescriptions. The more activities with feedback, the more personalized Saturday becomes. Encourage athletes to submit feedback — even simple ratings help.

​
Activity type inference

If your platform has activity metadata but not a clean type, Saturday can infer it: 
POST /v1/inference/activity-type

{
  "title": "Morning jog around Green Lake",
  "description": "Easy recovery after yesterday's intervals",
  "tags": ["recovery", "outdoor"]
}
Response: 
{
  "inferred_type": "run",
  "confidence": 0.95,
  "intensity_hint": "easy"
}
For multi-sport titles like “Bike/run brick”, use POST /v1/inference/activity-type/brick.