Coach API

The Coach API exposes a coach’s Saturday surface over a coach-scoped REST API, and over an MCP connector: the per-athlete fueling rollup, AI reports, the roster’s needs-attention markers, and the notification and alerting settings. It is built for a coach who wants to automate fueling monitoring: read who needs attention, pull a report, and configure alert rules and digests across a whole roster programmatically.

Tier requirements. Coach endpoints require the Pro Coach tier or above (Pro Coach, Head Coach, Business, Enterprise). Two further gates sit above that line: minting a coach API key in the portal requires Business or Enterprise plus an org-admin role, and webhook delivery requires Business or Enterprise. A Pro Coach or Head Coach therefore reaches the whole surface through the OAuth connector, and reaches it through an API key only if someone on a Business plan minted one.

When a tier lapses. On an OAuth token, the coach tools stop resolving and coach endpoints return 404, while the coach keeps their own athlete data. There is no error and no separate “downgrade” call. On a coach API key there is no athlete-self facet to fall back to, so the request is refused outright with 403 coach_tier_required.

Authentication

Two ways to authenticate as a coach. Both resolve to the same coach identity and roster.

Method	Token	Best for
Coach API key	`cp_live_…` / `cp_test_…` (Bearer)	Scripts, automations, server-to-server
OAuth2 (coach scopes)	OAuth2 access token (Bearer)	The Claude.ai connector / user-delegated apps

Coach API keys are minted in the coach portal under Admin → API Keys. Pass the key as a Bearer token:

curl -H "Authorization: Bearer cp_live_..." https://api.saturday.fit/v1/coach/roster

OAuth2 coaches use the connector OAuth flow with coach scopes (coach:roster, coach:reports, coach:alerts, coach:webhooks). Because a coach is also an athlete, the same OAuth token acts as an athlete-self token on /v1/athletes/*.

Scopes and capabilities

The coach’s token or key carries scopes that map to capabilities. A route is reachable only when the token confers the matching capability; otherwise it returns the uniform 404.

Capability	OAuth scope	API-key scope	Grants
Read roster + rollups + sessions	`coach:roster`	`roster:read`, `roster:write`, `org:read`, `org:write`	`GET /v1/coach/roster`, `…/fueling-rollup`, `…/sessions/…`
Read reports + digest	`coach:reports`	`org:read`, `org:write`	`…/report`, `/v1/coach/roster/digest`
Write alert + report config	`coach:alerts`	`roster:write`, `org:write`	`/v1/coach/config/*`
Manage webhooks	`coach:webhooks`	`webhooks:manage`	`/v1/coach/webhooks/*`

The two vocabularies are unioned, never translated, so a key keeps exactly the reach its scopes confer. roster:read alone does not open the report routes; pick org:read or higher when a key needs reports. Keys minted before scoped keys existed carry a single * scope and hold all four capabilities.

Roster confinement. Every {athlete_uid} you pass is checked against your roster. An athlete who isn’t on your roster, and an athlete who doesn’t exist, both return 404 resource_not_found. The two cases are indistinguishable, so the API never reveals whether an athlete exists.

Reads

List the roster

GET /v1/coach/roster returns every athlete you coach, each with a needs-attention summary over the look-back window.

curl -H "Authorization: Bearer cp_live_..." \
  "https://api.saturday.fit/v1/coach/roster?window=14"

Query param	Values	Default
`window`	`7`, `14`, `30`	your configured report window

{
  "coach_uid": "coach_abc",
  "window": 14,
  "athletes": [
    {
      "athlete_uid": "ath_123",
      "flagged": true,
      "flagged_count": 2,
      "top_reasons": ["Sodium 57%", "1 symptom"],
      "session_count": 6
    }
  ]
}

The markers come from Saturday’s single shared concern definition, so they match the coach portal table and the digest exactly. An athlete who fueled well shows flagged: false.

Roster digest (flagged-only)

GET /v1/coach/roster/digest returns the same data for athletes who crossed a concern bar this window, most-flagged first. Athletes who did not cross a bar are omitted, which is what makes this the useful call on a large roster.

{
  "coach_uid": "coach_abc",
  "window": 7,
  "flagged_count": 3,
  "total_count": 48,
  "flagged": [
    {
      "athlete_uid": "ath_123",
      "flagged": true,
      "flagged_count": 2,
      "top_reasons": ["Sodium 57%", "1 symptom"],
      "session_count": 6
    }
  ]
}

flagged carries the same entry shape as GET /v1/coach/roster above, ordered most-flagged first. flagged_count counts the entries in it; total_count counts the whole roster.

Per-athlete fueling rollup

GET /v1/coach/athletes/{athlete_uid}/fueling-rollup returns one athlete’s in-window sessions (the same table the portal renders) plus the concern summary and the resolved cutoffs that produced the markers.

Query param	Values	Default
`window`	`7`, `14`, `30`	your configured window
`focus`	`worst`, `rolling`, `key`	your configured focus

{
  "athlete_uid": "ath_123",
  "window": 14,
  "focus": "rolling",
  "sessions": [
    {
      "activity_id": "act_789",
      "date_millis": 1749480000000,
      "type": "ride",
      "duration_min": 210,
      "is_race": false,
      "carb_pct": 0.82,
      "sodium_pct": 0.57,
      "fluid_pct": 0.94,
      "consumed_carb_g": 172,
      "consumed_sodium_mg": 1140,
      "consumed_fluid_ml": 2350,
      "user_rating": 3,
      "symptoms": { "cramp": 1 },
      "sleep_hours": 6.5
    }
  ],
  "concern": {
    "flagged": true,
    "flagged_count": 2,
    "top_reasons": ["Sodium 57%", "1 symptom"]
  },
  "settings_resolved": {
    "report_window_days": 14,
    "report_focus": "rolling",
    "concern_carb_cutoff": 0.7,
    "concern_sodium_cutoff": 0.7,
    "concern_fluid_cutoff": 0.7,
    "hyponatremia_fluid_min": 0.9,
    "hyponatremia_sodium_max": 0.5
  }
}

The session object above is abbreviated. Each entry also carries the as-used and suggested prescription totals, prep fidelity, leftover reuse, report source and completeness, intensity, the profile snapshot, opaque vessel_reports and weather maps, and the derived adherence_vs_suggested, dial_down_gap, and per_hour triples. The adherence fractions are uncapped, so a value above 1.0 is genuine over-consumption rather than an error. Every missing value stays null, never 0, and an absent symptoms key is not a zero.

AI report

GET /v1/coach/athletes/{athlete_uid}/report returns the AI-generated fueling report: a third-person narrative grounded only in the athlete’s own numbers, plus the structured concern summary behind it, so an agent can quote the prose or compute on the data.

Query param	Values	Notes
`window`	`7`, `14`, `30`	look-back
`focus`	`worst`, `rolling`, `key`	report focus
`refresh`	`true`	force regeneration even if a cached report exists
`format`	`pdf`	return the report as a downloadable PDF instead of JSON

{
  "athlete_uid": "ath_123",
  "window": 14,
  "focus": "rolling",
  "narrative": "Over the last two weeks, this athlete …",
  "concern": {
    "flagged": true,
    "flagged_count": 2,
    "top_reasons": ["Sodium 57%", "1 symptom"]
  },
  "generated_at": 1749500000000,
  "latest_session_ms": 1749480000000,
  "from_cache": true
}

Served from cache unless a newer session has landed or refresh=true.

Session detail

GET /v1/coach/athletes/{athlete_uid}/sessions/{activity_id} drills into one session: the full per-session projection (planned-vs-actual fueling, symptoms, vessel reports, weather, sleep) plus the concern markers that session crossed.

Configuration

Most of the Coach API is a configuration surface. Anything a coach can configure in the portal is configurable here: channels, triggers, per-nutrient thresholds, the overall/group/athlete scope hierarchy, consolidation, cadence, quiet hours, and AI-report defaults. The portal UI and the API are two views of one config model.

Scope precedence. Config applies at one of three scopes: overall (the whole roster), group (a coach group), or athlete (one athlete). When resolving what an athlete sees, the most specific scope wins (athlete over group over overall). scope_id is required for group and athlete, and omitted for overall.

Notification rules

GET /v1/coach/config/notification-rules?scope=overall reads the rules set at exactly that scope, not the merged resolution. PUT /v1/coach/config/notification-rules replaces the rule set at a scope. It is an idempotent upsert: re-running with the same body is a no-op, so no per-request idempotency key is needed.

curl -X PUT https://api.saturday.fit/v1/coach/config/notification-rules \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "group",
    "scope_id": "grp_elite",
    "rules": {
      "notification_rules": {
        "under_fuel": { "enabled": true, "channels": ["email", "webhook"], "cadence": "realtime", "urgent_threshold": 0.6 },
        "hyponatremia_pattern": { "enabled": true, "channels": ["push"], "cadence": "realtime" }
      },
      "combinators": [
        { "trigger_a": "under_fuel", "trigger_b": "symptom", "channel": "push", "cadence": "realtime" }
      ],
      "quiet_hours": { "enabled": true, "start": "22:00", "end": "06:00", "tz": "America/Denver" }
    }
  }'

Triggers: under_fuel, symptom, low_rating, hyponatremia_pattern, dial_down, sleep_trend, went_quiet. Channels: in_portal, email, push, webhook. (SMS is not yet supported.) Cadence: realtime (sent as it happens) or digest (bundled into one daily item per athlete). Thresholds are fractions in (0,1]. urgent_threshold is the urgent band. amber_threshold is optional and decouples this trigger’s marker line from the shared cutoff; omit it to use the resolved concern cutoff. Combinators are bounded two-trigger ANDs: both legs must be markers on the same session (“sodium short AND a cramp”). Exactly two triggers, with no OR, NOT, or nesting.

Presets

POST /v1/coach/config/preset applies a named starting point at a scope, which you can then tweak rule by rule.

curl -X POST https://api.saturday.fit/v1/coach/config/preset \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "scope": "overall", "preset": "balanced" }'

Preset	Behavior
`hands_off`	in-portal only, no pings
`balanced`	core concerns on email, daily digest
`hands_on`	all triggers, real-time urgent push

AI-report & concern settings

GET / PUT /v1/coach/config/report-settings reads/upserts the report window/focus defaults and any overridden concern cutoffs at a scope. Unset fields fall through to the broader scope.

curl -X PUT https://api.saturday.fit/v1/coach/config/report-settings \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "athlete",
    "scope_id": "ath_123",
    "settings": {
      "ai_report_window_days": 30,
      "ai_report_focus": "key",
      "concern_sodium_cutoff": 0.65
    }
  }'

Athlete data is read-only. The Coach API never writes an athlete’s fueling data, debriefs, or prescriptions. A coach can configure only their own alerts, reports, groups, and thresholds.

Webhooks

A webhook is another delivery channel on the alerts you already configure ("channels": ["webhook"]). Register an endpoint, then select webhook as a channel on any rule.

Webhook delivery requires the Business or Enterprise tier. Registration succeeds at Pro Coach and Head Coach, but no events are delivered until the tier qualifies, and delivery stops within the same billing check if the tier later drops.

POST /v1/coach/webhooks registers an endpoint and returns the signing secret once.

curl -X POST https://api.saturday.fit/v1/coach/webhooks \
  -H "Authorization: Bearer cp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://my-system.example.com/saturday", "events": ["concern.detected", "athlete.needs_attention"] }'

{
  "id": "wh_abc",
  "coach_uid": "coach_abc",
  "url": "https://my-system.example.com/saturday",
  "events": ["concern.detected", "athlete.needs_attention"],
  "active": true,
  "created_at": 1749500000000,
  "secret": "whsec_…"
}

secret appears in this response and never again. GET /v1/coach/webhooks omits it, and there is no endpoint that re-reads it. Store it when you register, or delete the endpoint and register a new one to get a fresh secret.

Method · path	Action
`GET /v1/coach/webhooks`	list endpoints (secrets never returned)
`POST /v1/coach/webhooks`	register (secret returned once)
`DELETE /v1/coach/webhooks/{id}`	delete an endpoint
`POST /v1/coach/webhooks/{id}/disable`	disable (stop delivery, keep the endpoint)
`POST /v1/coach/webhooks/{id}/enable`	re-enable

Event types: concern.detected and athlete.needs_attention, which an empty events list subscribes you to, plus coach.message.sent, which is opt-in and only fires for Enterprise coaches. The URL must be public https; internal, metadata, and loopback URLs are rejected at registration. Deliveries are signed with HMAC-SHA256 in the X-Saturday-Signature header using the secret returned at registration, retried with backoff, and auto-disabled after 15 consecutive failures. See Webhooks for verifying signatures.

Full identity

Coach API responses carry full athlete identity: names and data exactly as the coach sees them in the portal. The coach owns the coaching relationship, so the API has no de-identification layer (the export feature’s identity levels are a portal and export concern). Handling that PII downstream is your responsibility. See the data policy.

Rate limits

Coach principals get 50 requests per second sustained with a burst of 500, so a 500-athlete roster pull or digest completes in one turn without paging penalties. These limits are set for abuse protection rather than capacity management. See rate limiting.

SDKs

Both the TypeScript and Python SDKs expose the coach surface as a coach resource:

import Saturday from '@saturdayinc/sdk';

const saturday = new Saturday({ apiKey: 'cp_live_...' });

const digest = await saturday.coach.rosterDigest({ window: 7 });
const report = await saturday.coach.report('ath_123', { window: 14 });

await saturday.coach.applyPreset({ scope: 'overall', preset: 'balanced' });
const wh = await saturday.coach.registerWebhook('https://my-system.example.com/saturday');
// wh.secret is returned once; store it now

from saturday import Saturday

client = Saturday(api_key="cp_live_...")

digest = client.coach.roster_digest(window=7)
report = client.coach.report("ath_123", window=14)

client.coach.apply_preset(scope="overall", preset="balanced")
wh = client.coach.register_webhook("https://my-system.example.com/saturday")
# wh["secret"] is returned once; store it now

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Coach API

Coach API

Authentication

Scopes and capabilities

Reads

List the roster

Roster digest (flagged-only)

Per-athlete fueling rollup

AI report

Session detail

Configuration

Notification rules

Presets

AI-report & concern settings

Webhooks

Full identity

Rate limits

SDKs

​Coach API

​Authentication

​Scopes and capabilities

​Reads

​List the roster

​Roster digest (flagged-only)

​Per-athlete fueling rollup

​AI report

​Session detail

​Configuration

​Notification rules

​Presets

​AI-report & concern settings

​Webhooks

​Full identity

​Rate limits

​SDKs

Coach API

Authentication

Scopes and capabilities

Reads

List the roster

Roster digest (flagged-only)

Per-athlete fueling rollup

AI report

Session detail

Configuration

Notification rules

Presets

AI-report & concern settings

Webhooks

Full identity

Rate limits

SDKs