Create a planned workout
create_planned_trainingCreate a planned training workout on the calendar of one or more athletes, of a group, or of yourself. Required: date_start, name, sport. Audience is optional — At most one of "athletes" or "group" — never both. Omit both to target your own calendar (self). Express targets portably (zone, % of metric): the server resolves absolute values per athlete. If no schema field expresses a detail of the coach's intent, put it in the comment of the relevant node — never approximate it into another field, never drop it. If a request expands to more than 3 creations, updates or deletions, do not call this tool in a loop: send them all as one POST batch/ via nolio_api_write with dry_run=true (PATCH and DELETE on planned// and library// included), get the user's go-ahead on a plain-language recap of what will change on whose calendar, then resend the same operations with the returned confirm_token. Before scheduling anything on a period, read what is already there in one call: get_calendar with mode='planned' over the window (and athlete for a managed athlete) renders the workouts, competitions, cycles, notes and quizzes at once; surface the conflicts before proposing. Returns the normalized event with a human-readable summary: check it against the request. A multi-week plan is more than isolated workouts: the calendar also carries the A-race goal (posted first, the plan hangs off it), cycles (mesocycles of one to several weeks, on planned/cycles/) that structure the base/build/peak/taper phases, and notes as markers (reminders, rest days, key dates). A hand-built plan usually combines all of these, not workouts alone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rpe | No | Planned RPE (0-10) — the coach's intended effort. | |
| name | Yes | Workout title. | |
| tags | No | Public tag ids from list_tags (e.g. tag_…) — your own tags, existing only, no creation here. | |
| time | No | Start time, HH:MM. Mutually exclusive with "moment" — provide at most one of the two. | |
| color | No | Hex color overriding the sport color, e.g. "#1E64E6". | |
| group | No | Public group id from list_athletes (e.g. grp_…), for a collective workout. At most one of "athletes" or "group" — never both. Omit both to target your own calendar (self). | |
| sport | Yes | The workout's sport: the `sport` field (spt_…) of a list_sports entry of the audience, never its `id` (spu_…). Never guess. | |
| moment | No | Part of day. Mutually exclusive with "time" — provide at most one of the two. | |
| dry_run | No | Validate without writing anything. Problems found on the workout steps and targets (zones, metrics, exercises) come back together, one per step or target; any other problem (payload shape, athlete, sport, date, tags) comes back alone: fix it and dry run again until it comes back valid. | |
| tonnage | No | Planned total tonnage (reps x load of the weighted sets): to override the total derived from the structured content. Null goes back to the derived total. | |
| workout | No | Optional structured content — a simple planned workout without it is a common, legitimate case. Patching it to null clears the structure but NOT duration/distance/rpe: null those explicitly too if they were derived from it. | |
| athletes | No | Public athlete ids from list_athletes (e.g. usr_…) — an array even for a single athlete. At most one of "athletes" or "group" — never both. Omit both to target your own calendar (self). | |
| distance | No | Planned total distance — for a workout without structured content, or to override the total derived from it. | |
| duration | No | Planned total duration — for a workout without structured content, or to override the total derived from it. | |
| show_rpe | No | Make the planned RPE visible to the athlete. Default false: coach-only, so it does not bias the athlete's perceived effort. | |
| date_start | Yes | Scheduled date, YYYY-MM-DD. Relative dates always resolve forward: a named weekday = the next occurrence, today included. Past dates are allowed (coaches backfill plans) — but confirm with the user before creating when a resolved date unexpectedly lands in the past. | |
| recurrence | No | Repeat as on the web. A rule change requires recurrence_action following or all and rebuilds that selection; null with action all keeps only the selected event. The audience (athletes or group) only changes with action one, one occurrence at a time, and never together with a rule change. | |
| coggan_load | No | Coggan load (TSS) set by hand, overriding the value computed from the structured content or estimated from RPE and duration. Kept until set to null, which goes back to the computed value. Read `load.coggan` for the load in effect and `load.coggan_source` for where it comes from (`rpe` = estimate, never set by hand). | |
| description | No | Plain text shown at the top of the workout. Line breaks are preserved, use them to separate distinct instructions. Accepted only while the workout has no description: to change an existing one, send description_html. | |
| elevation_gain | No | Planned elevation gain — not derivable from the structured content. | |
| elevation_loss | No | Planned elevation loss, not derivable from the structured content. | |
| description_html | No | The description as stored, in HTML, without the structured workout. The only way to change a description that is already set: read it with with_description_html=true, edit only what must change, keep every other tag, and send it back whole. Null on a read that did not ask for it, ignored on write. |