Trainee plans and workouts

The workouts tab of the trainee app is served by eight endpoints on the main trainee router. One read returns every active training plan fully resolved. The writes record workout logs, the trainee’s own exercise swaps and technique videos for coach review. Mount: /v1/trainee, router traineeRouter in src/modules/trainee/trainee.routes.ts. Lane: trainee. Every endpoint on this page uses both guards: the trainee token and the app access check. A frozen or ended subscription returns 403 with details.reason = "APP_LOCKED", and preview tokens can only call the GET endpoints. See Authentication.

Reading plans

`GET /v1/trainee/workouts`

Returns all active training plans with their days and exercises, the current week strip and the movement requirement. Auth: trainee token and app access. No parameters. What the service does, in order:

Loads every Program of type TRAINING with status ACTIVE for the trainee, newest updatedAt first, plus the latest 200 completed workout logs (WORKOUT_LOG_SCAN), the trainee’s technique videos, the last performed date per day label, and the trainee’s stored substitutions.
Normalizes each plan’s content with normalizeTrainingContent, which migrates older content shapes on read. A file plan (a program with pdfUrl set, either a PDF or a site link) is never normalized and is returned with kind: "file" and no days.
For plans with the automatic alternatives switch on (meta.autoAlts), replaces each row’s alternatives with ranked automatic picks for the prescribed exercise. The coach’s own list stays stored and comes back when the switch is turned off.
Applies the trainee’s substitutions. A substitution only applies while the row still prescribes the exercise it was made against (fromExerciseId). When it applies, the coach’s original is placed first in alternatives so the trainee can switch back.
Resolves each exercise id to a name, image, video, instructions and target muscle, applying the studio’s per-exercise overrides (ExerciseStudioOverride) over the shared library row.
Attaches history to every row and alternative: the sets from the most recent log of that exercise, the personal record, the technique video prompt and any unseen coach feedback.

Response: 200.

{
  "ok": true,
  "data": {
    "plans": [
      {
        "id": "cm2q3w7ya000al908c6t1n4xb",
        "name": "Strength block A",
        "kind": "regular",
        "pdfUrl": null,
        "workoutsPerWeek": 4,
        "completedThisWeek": 2,
        "days": [
          {
            "id": "d1",
            "label": "A",
            "focus": "Chest · Triceps",
            "exerciseCount": 6,
            "estimatedDurationMinutes": 52,
            "lastPerformedAt": "2026-10-04T16:02:11.000Z",
            "cardio": { "minutes": 20, "activities": ["walking"] },
            "rirColumn": true,
            "strength": [
              {
                "id": "r1",
                "exerciseId": "cm0ex4bench0001",
                "name": "Bench press",
                "image": "https://cdn.example.com/exercises/bench.jpg",
                "video": "https://cdn.example.com/exercises/bench.mp4",
                "instructions": "Keep your shoulder blades pinned.",
                "muscle": "Chest",
                "sets": "3",
                "reps": "8-12",
                "repType": "range",
                "repsHigh": "12",
                "rest": "1:30",
                "weight": "60",
                "rir": "2",
                "tempo": "",
                "notes": "",
                "setRows": [
                  { "id": "s1", "type": "warmup", "reps": "12", "repType": "fixed", "repsHigh": "", "weight": "40", "rest": "1:00", "note": "" },
                  { "id": "s2", "type": "working", "reps": "8-12", "repType": "range", "repsHigh": "12", "weight": "60", "rest": "1:30", "note": "" }
                ],
                "supersetParentId": null,
                "alternatives": [
                  {
                    "exerciseId": "cm0ex4dbpress0002",
                    "name": "Dumbbell press",
                    "image": null,
                    "video": null,
                    "instructions": null,
                    "muscle": "Chest",
                    "lastSets": [],
                    "pr": null,
                    "techniqueVideo": null,
                    "coachFeedback": null
                  }
                ],
                "lastSets": [
                  { "setNumber": 1, "weight": 60, "reps": 10 },
                  { "setNumber": 2, "weight": 60, "reps": 9 }
                ],
                "pr": { "weight": 62.5, "reps": 8 },
                "techniqueVideo": { "mode": "coachDemand", "required": true, "reason": "FIRST_TIME", "completedCount": 0 },
                "coachFeedback": null,
                "substitutedFrom": null
              }
            ]
          }
        ]
      }
    ],
    "week": [
      { "date": "2026-10-04", "weekday": 0, "completed": true, "workoutLabel": "A" },
      { "date": "2026-10-05", "weekday": 1, "completed": false, "workoutLabel": null }
    ],
    "movement": null
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

week always holds seven entries, Sunday to Saturday of the current week in the trainee’s time zone. It is shortened above. With no active training plan the response is { "plans": [], "week": [...], "movement": null }.

Plan fields

string

regular or file. A file plan has pdfUrl set, days: [], and workoutsPerWeek from content.meta.workoutsPerWeek or null.

string

The plan’s display name when set, else its internal name (traineePlanName).

number

Completed logs this week that belong to the plan. A log with programId counts for that plan only. A log without one counts when its label matches one of the plan’s day labels. For a file plan the label to match is the plan name.

Day fields

string

The distinct muscles of the day’s rows joined with a middle dot.

number

(work seconds + rest seconds) x 1.1, plus the day’s cardio minutes when the plan requires cardio. Work is 3 seconds per rep using the top of a rep range, or the stated seconds or minutes for timed sets. A row with no set breakdown counts its sets value, defaulting to 3. The mobile app mirrors this formula.

string | null

The latest completed log whose label equals this day’s label.

object | null

Present when the plan’s movement requirement includes cardio. activities values are walking, running, stairs and cycling.

boolean

Whether the coach enabled the RIR column (meta.columns.rir). The app shows the RIR input only when this is true.

Row fields

string

For repType: "range" this is low-high, for example 8-12, so older app builds that only read reps still work. repType is fixed, range, seconds or minutes.

array

The per-set breakdown. type is warmup, working or drop. Empty per-set values inherit the row’s.

string | null

The id of the row this one is super-setted with.

array

The sets marked done in the most recent completed log that contains this exercise. Used to prefill weight and reps.

object | null

The trainee’s record for the exercise across the scanned logs. A set counts only when it is marked done: true, has reps above zero and, for a weighted set with a target, reached at least 80 percent of targetReps. The heaviest weight wins. Bodyweight exercises rank by reps. The rule lives in client-tracking.compute.ts and is shared with the coach views.

object | null

null when the row’s mode is none and there is no open coach request. Otherwise { mode, required, reason, completedCount }. mode is free or coachDemand. reason is FIRST_TIME, EVERY_N, COACH_REQUEST or null.

object | null

The newest reviewed video of this exercise with a coach note the trainee has not seen: { videoId, note, reviewedAt }.

object | null

Set when the trainee’s own swap is applied: { exerciseId, name } of the coach’s original.

Technique video prompts

evaluatePrompt in technique-prompts.ts decides whether a video is required:

A coach’s one-shot request (techniqueVideo.requestedAt on the row) is open until the trainee uploads a video of that exercise after the request time. While open, the prompt is { mode: "coachDemand", required: true, reason: "COACH_REQUEST" }.
In coachDemand mode the quota is 1 when firstTime is on, plus one for every everyN completed performances of the exercise. A video is required while the trainee has submitted fewer videos than the quota.
In free mode a video is never required.

An exercise counts as performed once per workout log, when at least one of its sets is marked done.

Next workout

The API does not return a “next” flag on days. The rule is nextTrainingDay: the day after the most recently performed one, wrapping around, or the first day when nothing was performed. The app applies the same rule, and the server uses it for GET /v1/trainee/home and for the movement block.

Movement requirement

movement is built from the newest active plan whose meta.requirement.on is true. It is null when no plan has a requirement.

{
  "mode": "both",
  "compensates": false,
  "cardio": {
    "scope": "perWorkout",
    "activities": ["walking", "cycling"],
    "todayTargetMinutes": 20,
    "todayMinutes": 0,
    "weeklyTargetMinutes": 80,
    "weeklyMinutes": 40,
    "met": false
  },
  "steps": { "dailyGoal": 10000, "todaySteps": 6200, "weeklyGoal": 70000, "weeklySteps": 31500, "met": false },
  "todayMet": false
}

mode is cardioOnly, stepsOnly, both or bothCompensated. With bothCompensated, meeting either cardio or steps is enough for todayMet. Cardio minutes come from CardioLog rows and steps from DailyMetric.steps, both for the current week. Logging them is covered on Trainee tracking. Errors: none beyond the lane errors.

Logging

`POST /v1/trainee/workouts/log`

Records one workout session. Auth: trainee token and app access.

string

The plan the workout belongs to. Send it. Logs without it are matched to plans by label only.

string

The plan day id. The coach’s workout history groups sessions by it, because coaches rename day labels.

string

The day label at the time of the workout, for example A. For a file plan’s mark-done button the app sends the plan name.

string

Trimmed, at most 1000 characters. An empty note is not stored.

number

Non-negative integer.

boolean

default:"true"

false records an unfinished session. Only completed logs count for history, streaks, records and weekly progress.

object[]

default:"[]"

One object per exercise. The schema accepts any object. The fields the server reads are listed below.

The shape of entries is a contract between the app and every reader of WorkoutLog.entries. The schema does not enforce it, so follow it exactly:

[
  {
    "exerciseId": "cm0ex4bench0001",
    "name": "Bench press",
    "sets": [
      { "setNumber": 1, "weight": 60, "reps": 10, "targetReps": 12, "rir": "2", "done": true },
      { "setNumber": 2, "weight": 60, "reps": 9, "targetReps": 12, "rir": "1", "done": true },
      { "setNumber": 3, "weight": 60, "reps": 0, "targetReps": 12, "done": false }
    ]
  }
]

Field	Read by	Notes
`exerciseId`	Last sets, records, technique counts	Entries without it are ignored by those readers
`name`	History detail, partner API	Shown as the exercise name in `GET /v1/trainee/workouts/history/:id`
`sets[].setNumber`	Last sets, history	A number. Sets without it are skipped for prefill
`sets[].weight`, `sets[].reps`	All readers	Numbers. The history view also accepts numeric strings
`sets[].targetReps`	Records	The prescribed reps, used for the 80 percent rule
`sets[].rir`	History	A non-empty string
`sets[].done`	All readers	`false` marks a skipped set. Records require `true`. A set with no `done` flag counts in history when it has reps or weight

programId is not checked against the trainee’s own programs on this endpoint. It only has to be an existing program id. What the service does:

Creates a WorkoutLog with performedOn set to the server’s current time. The client cannot backdate a workout.
When completed is true, counts the trainee’s completed logs to get workoutNumber.
When this is the trainee’s first completed workout, calls the subscription starter with FIRST_WORKOUT. A subscription that was waiting for the first workout starts now. Deleting the log later does not undo that.

The endpoint sends no push notification and creates no inbox item. Coach-side views read the log on demand, and scheduled jobs pick up inactivity separately. Response: 201. The created row plus workoutNumber.

{
  "ok": true,
  "data": {
    "id": "cm2r5k1pc000dl908w2e8z7mf",
    "clientId": "cm2k9x1ab0001l508u3f7q2wd",
    "programId": "cm2q3w7ya000al908c6t1n4xb",
    "performedOn": "2026-10-07T16:40:12.000Z",
    "label": "A",
    "dayId": "d1",
    "note": null,
    "entries": [],
    "durationSec": 3120,
    "completed": true,
    "createdAt": "2026-10-07T16:40:12.000Z",
    "workoutNumber": 50
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

workoutNumber is the trainee’s lifetime count of completed workouts, used by the share screen. It is null for an unfinished log. entries is echoed as stored and shortened here. Errors:

Code	Status	When
`VALIDATION`	422	Body fails the schema, for example `note` over 1000 characters or `entries` not an array of objects
`CONFLICT`	409	`related resource constraint failed` when `programId` does not exist

`GET /v1/trainee/workouts/history`

Lists the trainee’s completed workouts, newest first. Auth: trainee token and app access. No parameters. Returns at most 100 logs (WORKOUT_HISTORY_LIMIT), ordered by performedOn then createdAt, both descending. Unfinished logs are excluded. Response: 200.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cm2r5k1pc000dl908w2e8z7mf",
        "label": "A",
        "performedOn": "2026-10-07T16:40:12.000Z",
        "durationSec": 3120,
        "setCount": 17,
        "volumeKg": 5240,
        "exerciseCount": 6
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

setCount, volumeKg and exerciseCount are computed by readWorkoutLog from entries. Only performed sets count. Volume is the sum of weight times reps for sets with both above zero, rounded to a whole kilogram. label is an empty string when the log has none. Errors: none beyond the lane errors.

`GET /v1/trainee/workouts/history/:id`

Returns one completed workout with its exercises and sets. Auth: trainee token and app access.

string

required

The workout log id.

Response: 200.

{
  "ok": true,
  "data": {
    "id": "cm2r5k1pc000dl908w2e8z7mf",
    "label": "A",
    "dayId": "d1",
    "performedOn": "2026-10-07T16:40:12.000Z",
    "durationSec": 3120,
    "setCount": 17,
    "volumeKg": 5240,
    "exerciseCount": 6,
    "workoutNumber": 50,
    "exercises": [
      {
        "name": "Bench press",
        "sets": [
          { "setNumber": 1, "reps": 10, "weight": 60, "rir": "2" },
          { "setNumber": 2, "reps": 9, "weight": 60, "rir": "1" }
        ]
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

workoutNumber is the ordinal of this workout among the trainee’s completed logs, counted up to this log’s performedOn and createdAt. Exercise names come from the name stored in each entry, not from the library, so they show what the trainee saw at the time. Exercises with no performed set are left out. Errors:

Code	Status	When
`NOT_FOUND`	404	`workout log not found`: no such log for this trainee, or the log is not completed

`DELETE /v1/trainee/workouts/log/:id`

Deletes one of the trainee’s workout logs. Auth: trainee token and app access.

string

required

The workout log id.

The delete is scoped by clientId, so a trainee can only remove their own logs. Records, last sets, streaks and weekly progress are all derived at read time, so they update on the next read. A subscription that the log started stays started. Response: 200.

{ "ok": true, "data": { "id": "cm2r5k1pc000dl908w2e8z7mf" }, "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD" }

Errors:

Code	Status	When
`NOT_FOUND`	404	`workout log not found`

Substitutions

`POST /v1/trainee/workouts/substitutions`

Saves the trainee’s own swap of one prescribed exercise for an approved alternative, so it becomes their default in future workouts. Sending the original exercise as the target removes the swap. Auth: trainee token and app access.

string

required

The training plan.

string

required

The plan day that holds the row.

string

required

The strength row id from GET /v1/trainee/workouts.

string

required

The exercise the coach currently prescribes on that row. Acts as a staleness guard.

string

required

The alternative to use. Equal to fromExerciseId means undo.

The swap is stored in its own table, TraineeExerciseSubstitution (unique on programId and rowId), not inside the program content. The coach’s editor rewrites the whole content blob on save, so anything stored there would be lost. Writing the side table also avoids bumping the program version, which would push a “your coach updated your plan” notification to the trainee who just tapped swap. Checks, in order:

The program must be one of the trainee’s active training programs.
The row must exist in the named day of the current content.
The row must still prescribe fromExerciseId.
For an undo, the stored substitution is deleted and the call ends.
toExerciseId must be offered for that row right now: one of the coach’s alternatives, or, when automatic alternatives are on, one of the automatic picks computed the same way the workouts read computes them.

Response: 200.

{ "ok": true, "data": { "saved": true }, "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD" }

An undo returns { "saved": false }. Errors:

Code	Status	When
`VALIDATION`	422	A field is missing or empty
`NOT_FOUND`	404	`training program not found`, or `exercise row not found in this program`
`CONFLICT`	409	`the coach has since changed this exercise`: the row no longer prescribes `fromExerciseId`. Refetch the plans
`BAD_REQUEST`	400	`that exercise is not an approved alternative`

Technique videos

`POST /v1/trainee/technique-videos`

Submits a technique video for coach review. Upload the file first with Trainee uploads and send the returned URL. Auth: trainee token and app access.

string

required

The uploaded video URL. Any non-empty string is accepted.

string

The exercise the video shows. Send it. Prompts and coach requests are tracked per exercise, and videos without an exercise are ignored by them.

string

A poster image URL.

Creates a TechniqueVideo row with status PENDING. A new upload of an exercise closes any open coach request for it, because the request only stands until a newer video exists. Response: 201. The created row.

{
  "ok": true,
  "data": {
    "id": "cm2s8n4vd000fl908a7h3k1qj",
    "clientId": "cm2k9x1ab0001l508u3f7q2wd",
    "exerciseId": "cm0ex4bench0001",
    "url": "https://cdn.example.com/media/7c2e19aa.mp4",
    "thumbnailUrl": null,
    "status": "PENDING",
    "coachNote": null,
    "voiceNoteUrl": null,
    "reviewedById": null,
    "reviewedAt": null,
    "feedbackSeenAt": null,
    "createdAt": "2026-10-07T16:45:02.000Z"
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Errors: VALIDATION (422) when url is missing or empty.

`POST /v1/trainee/technique-videos/:id/feedback-seen`

Marks the coach’s feedback on a video as seen, so it stops appearing as coachFeedback on the exercise. Auth: trainee token and app access.

string

required

The technique video id, taken from coachFeedback.videoId.

Sets TechniqueVideo.feedbackSeenAt to now. Calling it again just refreshes the timestamp. Response: 200.

{ "ok": true, "data": { "id": "cm2s8n4vd000fl908a7h3k1qj" }, "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD" }

Errors:

Code	Status	When
`NOT_FOUND`	404	`technique video not found`: no such video for this trainee

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Trainee plans and workouts

Reading plans

`GET /v1/trainee/workouts`

Plan fields

Day fields

Row fields

Technique video prompts

Next workout

Movement requirement

Logging

`POST /v1/trainee/workouts/log`

`GET /v1/trainee/workouts/history`

`GET /v1/trainee/workouts/history/:id`

`DELETE /v1/trainee/workouts/log/:id`

Substitutions

`POST /v1/trainee/workouts/substitutions`

Technique videos

`POST /v1/trainee/technique-videos`

`POST /v1/trainee/technique-videos/:id/feedback-seen`

​Reading plans

​GET /v1/trainee/workouts

​Plan fields

​Day fields

​Row fields

​Technique video prompts

​Next workout

​Movement requirement

​Logging

​POST /v1/trainee/workouts/log

​GET /v1/trainee/workouts/history

​GET /v1/trainee/workouts/history/:id

​DELETE /v1/trainee/workouts/log/:id

​Substitutions

​POST /v1/trainee/workouts/substitutions

​Technique videos

​POST /v1/trainee/technique-videos

​POST /v1/trainee/technique-videos/:id/feedback-seen

Reading plans

`GET /v1/trainee/workouts`

Plan fields

Day fields

Row fields

Technique video prompts

Next workout

Movement requirement

Logging

`POST /v1/trainee/workouts/log`

`GET /v1/trainee/workouts/history`

`GET /v1/trainee/workouts/history/:id`

`DELETE /v1/trainee/workouts/log/:id`

Substitutions

`POST /v1/trainee/workouts/substitutions`

Technique videos

`POST /v1/trainee/technique-videos`

`POST /v1/trainee/technique-videos/:id/feedback-seen`