---
search:
  tags:
    - Phases
    - PATCH
seo:
  description: >-
    Partially updates a phase (dates, goal, rate, calories, protein, note). The
    kind can't… Reference for the PATCH /api/phases/{id} endpoint in the skcal
    API.
sidebar:
  label: Edit a phase
  badge: PATCH
title: Edit a phase
type: openapi-operation
---
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}`

**Request body** (`application/json`, required)

The phase fields to change.

- `kind` (string) — Phase type; required to start a phase.
- `startDate` (string<date>) — First day of the phase (default today).
- `plannedEndDate` (string<date> | null) — Planned last day (YYYY-MM-DD); empty or null clears it.
- `goalWeightLb` (number | null) — Goal body weight in pounds (default the start weight projected over the planned length).
- `ratePctPerWeek` (number | null) — Planned weekly change as a percent of bodyweight; positive gains, negative loses.
- `dailyKcal` (integer | null) — Daily calorie target (default maintenance from logged data plus the rate's surplus or deficit).
- `proteinG` (integer | null) — Daily protein target in grams to set with the phase.
- `note` (string | null) — Free-text note, e.g. the reason for the phase.

Request body example:

```json
{
  "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"
}
```

**Responses**

- `200` — The updated phase.
- `400` — The request body or parameters failed validation.
- `404` — No matching resource owned by the caller.

Response example, 200:

```json
{
  "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"
    }
  }
}
```