Athletes

Athletes are the core entity in Saturday’s API. Each athlete has a profile of physical characteristics and fueling preferences that personalize their nutrition prescriptions. Athletes are partner-scoped: your organization can only reach athletes created through your API key. There is no cross-partner data access.

Creating an athlete

import os
import requests

response = requests.post(
    "https://api.saturday.fit/v1/athletes",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={
        "external_id": "your-user-12345",
        "name": "Alex Runner",
        "email": "alex@example.com",
        "sex": "male",
        "year_of_birth": 1990,
        "weight_kg": 70,
        "settings": {"sweat_level": 7, "saltiness": 5},
    },
)

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

const response = await fetch("https://api.saturday.fit/v1/athletes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "your-user-12345",
    name: "Alex Runner",
    email: "alex@example.com",
    sex: "male",
    year_of_birth: 1990,
    weight_kg: 70,
    settings: { sweat_level: 7, saltiness: 5 },
  }),
});

const athlete = await response.json();
console.log(`Saturday ID: ${athlete.id}`);

External IDs

The external_id field maps the Saturday athlete to your platform’s user. This is your user ID, not Saturday’s. Use it to look athletes up without storing Saturday’s own IDs.

Profile fields

Every field is optional at create time. The athlete’s fueling profile is what makes prescriptions exact, so the fields below split into two groups: the ones the engine needs before it will return exact numbers, and the ones that narrow the band further. An athlete missing any safety-core field gets a range instead of a number. See Athlete Onboarding.

Top-level fields

Field	Type	Description
`external_id`	string	Your platform’s user ID
`name`	string	Display name
`email`	string	Enables automatic linking to an existing Saturday subscriber
`sex`	string	`male`, `female`, or `intersex`
`year_of_birth`	integer	Used to derive age. The athlete must be 14 or older
`weight_kg`	number	Body weight, 20 to 250
`settings`	object	The fueling profile, below
`partner_plan`	string	Set to `annual` to assert bundle-offer eligibility
`org_id`	string	Organization affiliation; must reference an org you created

Saturday sets id, partner_id, created_at, updated_at, profile_complete, and subscription_status. Writes to those are ignored.

Settings: the fueling profile

settings holds the fields the engine reads. The 1-9 scales are odd-point selectors, not continuous sliders: send 1, 3, 5, 7, or 9.

Field	Type	Values	Safety-core
`sweat_level`	integer	1 (light) to 9 (heavy), default 5	Yes
`saltiness`	integer	1 (not salty) to 9 (very salty), default 5	Yes
`carb_experience`	string	`range_0_30`, `range_40_60`, `range_gt_70`	Yes
`usual_carb_consumption`	string	`range_lt_60`, `range_60_80`, `range_80_100`, `range_gt_100`	Yes
`satiety_level`	integer	1 (mostly whole food) to 9 (high-octane fuel), default 5	No
`fitness_level`	integer	1 (beginner) to 9 (elite), default 5	No
`carb_upper_limit_override`	integer	50 to 150 g/hr, default 150	No

carb_experience is the most carbohydrate per hour the athlete has ever fueled with; usual_carb_consumption is what they typically take. Both are stored as range tokens rather than numbers, because a range is what an athlete can answer without guessing.

Fueling concerns

Concerns are individual booleans inside settings, not a list of tags:

Field	Meaning
`muscle_cramps`	Prone to cramping during exercise
`gut_distress`	Prone to GI distress
`performance`	Prioritizing performance over comfort
`hunger`	Prone to hunger during exercise
`heat_tolerance`	Poor heat tolerance
`faintness`	Prone to feeling faint
`drinking_resistance`	Resistant to drinking during exercise
`thirst`	Excessive thirst during exercise

Sending any concern key marks the concerns question answered, including when you send it as false. An athlete who has never been asked and an athlete who answered “none of these” are different states to the precision engine, and only the second one counts as complete.

Settings change as athletes train their gut and their sweat rate adapts. A profile answered once and never revisited drifts. Re-ask carb_experience, usual_carb_consumption, and sweat_level periodically.

Listing athletes

GET /v1/athletes?limit=50&cursor=1737043200%7Cath_3Hd9

Pagination is cursor-based, not offset-based. limit defaults to 50 and is clamped to 1-200. The response carries pagination.next_cursor; pass it back as cursor for the next page, URL-encoded and unchanged, and stop when pagination.has_more is false. Add ?profile_complete=false to list only the athletes whose profiles are still short of exact numbers. That is your nudge list.

Updating an athlete

PATCH /v1/athletes/{id}

Include only the top-level fields you want to change. Unspecified top-level fields are not modified.

import os
import requests

response = requests.patch(
    "https://api.saturday.fit/v1/athletes/ath_abc123def456",
    headers={"Authorization": f"Bearer {os.environ['SATURDAY_API_KEY']}"},
    json={"weight_kg": 72, "email": "alex@example.com"},
)

const response = await fetch(
  "https://api.saturday.fit/v1/athletes/ath_abc123def456",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.SATURDAY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ weight_kg: 72, email: "alex@example.com" }),
  }
);

Updating the fueling profile

PATCH /v1/athletes/{id}/settings

The settings object is written as a unit. Send the athlete’s complete settings on every write, including the values you are not changing, or the omitted ones are cleared. Read the current values first with GET /v1/athletes/{id}/settings and merge on your side. The same replacement rule applies if you send a settings object through PATCH /v1/athletes/{id}. On create, on update and on calculate, Saturday rejects carb_upper_limit_override outside 50-150 g/hr and weight_kg outside 20-250 with a 400 of code out_of_range rather than clamping, so a bad value in your data surfaces at the boundary instead of distorting a prescription. Batch create reports the same code per item. Saturday is for athletes 14 and up. On create and on update, a year_of_birth that makes the athlete younger than 14 (the current year minus the birth year) is refused with a 400 of code under_minimum_age and param year_of_birth, and nothing in that request is saved. The message names the minimum age:

{
  "error": {
    "type": "invalid_request",
    "code": "under_minimum_age",
    "message": "Saturday is for athletes 14 and up, and year_of_birth 2014 is under that age. Nothing was saved. See https://docs.saturday.fit/guides/athletes",
    "param": "year_of_birth",
    "documentation_url": "https://docs.saturday.fit/errors#under_minimum_age",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

On update, year_of_birth must be a whole number; any other value is refused with invalid_value.

Deleting an athlete

Two endpoints delete, and they are not interchangeable.

DELETE /v1/athletes/{id}

Removes the athlete from your roster together with everything stored under them: activities, prescriptions, feedback, AI conversations, consent records, integration tokens, and gear. Connected providers are not told, and the request is not filed with the data warehouse.

POST /v1/athletes/{id}/delete

The erasure path. It deauthorizes connected providers, purges the athlete’s subcollections (activities, conversations, consent, integrations), and files the request the data warehouse honors.

Use POST /v1/athletes/{id}/delete for a GDPR erasure request. DELETE clears your copy of the athlete but does not revoke their provider connections or notify the data warehouse. Neither can be undone.

Export all data held for an athlete:

POST /v1/athletes/{id}/export

Returns JSON containing the athlete’s profile, every activity with its prescription and feedback, any conversations with Saturday’s assistant, and their consent records.

Settings schema

Fetch the global settings schema to build dynamic forms:

GET /v1/settings/schema

Returns each field’s type, valid range or option list, description, and default, so a settings UI does not have to hardcode Saturday’s requirements. This is a global schema, identical for every athlete; fetch one athlete’s current values with GET /v1/athletes/{id}/settings. For collecting the profile from scratch rather than editing it, GET /v1/onboarding/questions returns the same fields as athlete-facing questions with copy, ordering, and answer values. See Athlete Onboarding.

Getting Started

Core Guides

Integration Guides

Coach API

Platform

Athletes

Athletes

Creating an athlete

External IDs

Profile fields

Top-level fields

Settings: the fueling profile

Fueling concerns

Listing athletes

Updating an athlete

Updating the fueling profile

Deleting an athlete

Settings schema

​Athletes

​Creating an athlete

​External IDs

​Profile fields

​Top-level fields

​Settings: the fueling profile

​Fueling concerns

​Listing athletes

​Updating an athlete

​Updating the fueling profile

​Deleting an athlete

​Data export (GDPR)

​Settings schema

Athletes

Creating an athlete

External IDs

Profile fields

Top-level fields

Settings: the fueling profile

Fueling concerns

Listing athletes

Updating an athlete

Updating the fueling profile

Deleting an athlete

Data export (GDPR)

Settings schema