Edit a phase

Partially updates a phase (dates, goal, rate, calories, protein, note). The kind can’t change; start a new phase instead. Editing the open phase updates the targets too.

PATCH/api/phases/{id}

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.

Path parameters

idstring<uuid>required

Phase identifier (UUID).

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 fields to change.

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 updated phase.

okbooleanrequired

True once the edit is saved.

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

400

The request body or parameters failed validation.

errorstringrequired

Human-readable failure reason.

detailstring

Optional extra context, present on upstream failures.

404

No matching resource owned by the caller.

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

idpath*Phase identifier (UUID).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 PATCH 'https://app.skcal.fit/api/phases/3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f' \
  -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/3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f", {
  method: "PATCH",
  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.patch(
    "https://app.skcal.fit/api/phases/3f2c1a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f",
    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"
    }
  }
}

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

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