# Saturday API

> Nutrition intelligence for endurance athletes, as an API.

Saturday calculates personalized fuel, hydration, and electrolyte recommendations for endurance athletes from athlete profiles, activity parameters, and environmental conditions.

## Authentication

Authenticated API requests use a Bearer token in the Authorization header. Partner API keys use the `sk_test_` (sandbox) or `sk_live_` (production) prefix. Signup and public discovery endpoints do not require a key.

```
Authorization: Bearer $SATURDAY_API_KEY
```

Coaches use a separate surface with separate credentials: a `cp_live_` / `cp_test_` coach API key, or an OAuth2 token carrying coach scopes.

## Core Endpoints

- POST /v1/nutrition/calculate: calculate a fuel/hydration/electrolyte prescription
- POST /v1/nutrition/calculate/batch: batch calculate for multiple scenarios
- POST /v1/nutrition/products/compare: compare products against a prescription
- POST /v1/athletes: create an athlete profile
- GET /v1/athletes: list the partner's athletes
- POST /v1/athletes/{athlete_id}/activities: create an activity
- POST /v1/athletes/{athlete_id}/activities/{activity_id}/calculate: calculate that activity's prescription
- POST /v1/ai/conversations: start an AI-to-AI conversation with Saturday's assistant (SSE streaming)
- POST /v1/webhooks: register a webhook for real-time events

## Coach Endpoints

Requires the Pro Coach tier or above. Every athlete id is confined to the coach's roster.

- GET /v1/coach/roster: the roster with per-athlete needs-attention markers
- GET /v1/coach/roster/digest: flagged athletes only, most-flagged first
- GET /v1/coach/athletes/{athlete_uid}/fueling-rollup: in-window sessions plus the concern summary
- GET /v1/coach/athletes/{athlete_uid}/report: the AI fueling report, narrative plus structured data
- GET /v1/coach/athletes/{athlete_uid}/sessions/{activity_id}: one session's full projection plus the concern markers it crossed
- PUT /v1/coach/config/notification-rules: replace the alert rules at a scope
- POST /v1/coach/config/preset: apply hands_off, balanced, or hands_on at a scope
- POST /v1/coach/webhooks: register a coach webhook endpoint

## Safety

Every response includes safety metadata (confidence_score, warnings, max_safe_fluid_ml_per_hr, max_safe_sodium_mg_per_hr, not_instructions). Safety data is never gated behind subscription status. Bad hydration recommendations can cause exercise-associated hyponatremia, which kills athletes.

## Freemium Model

Subscribed athletes with complete profile and activity inputs get exact numbers. Incomplete inputs and free athletes get ranges. Check the range fields and precision object separately from tier. Safety data is complete either way.

## Data Use

Every response carries an `X-Saturday-Data-License` header. Response data is licensed for display to end users only. Training or fine-tuning models on it, aggregating it, reverse engineering the calculations, and redistributing it are all prohibited. See https://docs.saturday.fit/guides/data-policy.

## Documentation

- Full docs: https://docs.saturday.fit
- Coach API guide: https://docs.saturday.fit/guides/coach-api
- Claude connector, athlete and coach tools: https://docs.saturday.fit/guides/coach-connector
- Full LLM context: https://docs.saturday.fit/llms-full.txt
- MCP server: https://api.saturday.fit/mcp
- API root discovery: https://api.saturday.fit/v1/