Start a phase

Starts a bulk, cut, or maintenance phase and closes the open one. Omitted fields are filled in: start weight from the latest weigh-in, rate from the kind’s default (+0.25% / -0.5% / 0% bodyweight per week), goal weight projected to the planned end, and daily calories from data-driven maintenance plus the rate’s surplus or deficit. The phase’s numbers are written to the caller’s targets.

POST/api/phases

Authorization

__Secure-better-auth.session_tokenAPI key · cookierequired

Better Auth session. Signing in (Google or email magic link) sets an HttpOnly session cookie that scopes every request to that account. The web app and CLI use this; agents use the OAuth 2.1 flow of the MCP server.

AuthorizationBearer token · headerrequired

Personal API key sent as Authorization: Bearer skcal_…. Create and scope keys in the app under your profile → API keys. Keys default to full access; a scoped key is limited to its granted resource:action permissions and cannot manage other keys.

Query parameters

datestring<date>

The caller's local calendar day (YYYY-MM-DD), the default start or end day. Defaults to the server's UTC date.

Request body

requiredapplication/json

The phase to start.

kindstring

Phase type; required to start a phase.

Allowed:bulkcutmaintain

startDatestring<date>

First day of the phase (default today).

plannedEndDatestring<date> | null

Planned last day (YYYY-MM-DD); empty or null clears it.

goalWeightLbnumber | null

Goal body weight in pounds (default the start weight projected over the planned length).

ratePctPerWeeknumber | null

Planned weekly change as a percent of bodyweight; positive gains, negative loses.

dailyKcalinteger | null

Daily calorie target (default maintenance from logged data plus the rate's surplus or deficit).

proteinGinteger | null

Daily protein target in grams to set with the phase.

notestring | null

Free-text note, e.g. the reason for the phase.

Responses

200

The phase was started.

okbooleanrequired

True once the phase is started.

phasePhaserequired

A goal phase with its progress.

Show properties

idstring<uuid>required

Phase identifier.

kindstringrequired

Phase type.

Allowed:bulkcutmaintain

startDatestring<date>required

First day.

plannedEndDatestring<date> | nullrequired

Planned last day.

endedDatestring<date> | nullrequired

Day it ended; null while it's the open phase.

activebooleanrequired

True for the open phase.

startWeightLbnumber | nullrequired

Bodyweight at the start, in pounds.

goalWeightLbnumber | nullrequired

Goal bodyweight in pounds.

ratePctPerWeeknumber | nullrequired

Planned weekly change, percent of bodyweight.

dailyKcalTargetinteger | nullrequired

The phase's daily calorie target.

proteinTargetGinteger | nullrequired

The phase's daily protein target in grams.

notestring | nullrequired

Free-text note.

progressPhaseProgressrequired

Planned vs actual rate of change, from a least-squares fit over the phase's weigh-ins.

Show properties

weeksElapsednumberrequired

Weeks since the start (to the end, for a closed phase).

weeksPlannednumber | nullrequired

Planned length in weeks.

latestWeightLbnumber | nullrequired

Latest weigh-in within the phase, in pounds.

changeLbnumber | nullrequired

Change since the start, in pounds.

plannedLbPerWeeknumber | nullrequired

Planned weekly change in pounds.

actualLbPerWeeknumber | nullrequired

Actual weekly change in pounds (null before a week of weigh-ins).

actualPctPerWeeknumber | nullrequired

Actual weekly change as a percent of start weight.

statusstringrequired

Whether the actual rate is within a third of the plan.

Allowed:on_tracktoo_fasttoo_slownot_enough_data

closedPhaseIdstring | nullrequired

The phase this one closed, if one was open.

kcalSourcestringrequired

Where the calorie target came from; unchanged means there wasn't enough data to estimate maintenance.

Allowed:givenestimatedunchanged

maintenanceKcalinteger | nullrequired

The maintenance estimate used, if any.

400

The request body or parameters failed validation.

errorstringrequired

Human-readable failure reason.

detailstring

Optional extra context, present on upstream failures.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

datequeryThe caller's local calendar day (YYYY-MM-DD), the default start or end day. Defaults to the server's UTC date.

Bodyapplication/json

kindstringPhase type; required to start a phase.startDatestringFirst day of the phase (default today).plannedEndDatestringPlanned last day (YYYY-MM-DD); empty or null clears it.goalWeightLbnumberGoal body weight in pounds (default the start weight projected over the planned length).ratePctPerWeeknumberPlanned weekly change as a percent of bodyweight; positive gains, negative loses.dailyKcalintegerDaily calorie target (default maintenance from logged data plus the rate's surplus or deficit).proteinGintegerDaily protein target in grams to set with the phase.notestringFree-text note, e.g. the reason for the phase.

Request

curl -X POST 'https://app.skcal.fit/api/phases' \
  -H 'Cookie: __Secure-better-auth.session_token=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "bulk",
  "startDate": "2026-10-24",
  "plannedEndDate": "2027-01-16",
  "goalWeightLb": 180,
  "ratePctPerWeek": 0.25,
  "dailyKcal": 2900,
  "proteinG": 180,
  "note": "lean bulk for the winter"
}'

const response = await fetch("https://app.skcal.fit/api/phases", {
  method: "POST",
  headers: {
    "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"kind\": \"bulk\",\n  \"startDate\": \"2026-10-24\",\n  \"plannedEndDate\": \"2027-01-16\",\n  \"goalWeightLb\": 180,\n  \"ratePctPerWeek\": 0.25,\n  \"dailyKcal\": 2900,\n  \"proteinG\": 180,\n  \"note\": \"lean bulk for the winter\"\n}"
});

import requests

response = requests.post(
    "https://app.skcal.fit/api/phases",
    headers={
        "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"kind\": \"bulk\",\n  \"startDate\": \"2026-10-24\",\n  \"plannedEndDate\": \"2027-01-16\",\n  \"goalWeightLb\": 180,\n  \"ratePctPerWeek\": 0.25,\n  \"dailyKcal\": 2900,\n  \"proteinG\": 180,\n  \"note\": \"lean bulk for the winter\"\n}",
)

Response

{
  "ok": true,
  "phase": {
    "id": "3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f",
    "kind": "bulk",
    "startDate": "2026-10-24",
    "plannedEndDate": "2027-01-16",
    "endedDate": null,
    "active": true,
    "startWeightLb": 165.2,
    "goalWeightLb": 170.2,
    "ratePctPerWeek": 0.25,
    "dailyKcalTarget": 2900,
    "proteinTargetG": 180,
    "note": "lean bulk for the winter",
    "progress": {
      "weeksElapsed": 3.4,
      "weeksPlanned": 12,
      "latestWeightLb": 167.1,
      "changeLb": 1.9,
      "plannedLbPerWeek": 0.41,
      "actualLbPerWeek": 0.52,
      "actualPctPerWeek": 0.31,
      "status": "on_track"
    }
  },
  "closedPhaseId": null,
  "kcalSource": "estimated",
  "maintenanceKcal": 2650
}

{
  "error": "weightKg must be 9-320 kg",
  "detail": "upstream model returned 500"
}