Create a mesocycle

Plans a mesocycle from a split template or explicit days of muscle slots. The last week is a deload. Week 1 starts each muscle at its MEV split across its slots, at 3 reps in reserve; later weeks are planned from what was lifted and the per-muscle feedback. One mesocycle can be active at a time.

POST/api/training/mesocycles

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 plan.

namestring

Name (default the template's).

weeksinteger

Total weeks including the final deload (default 5).

min 3 · max 8

startDatestring<date>

First day (default today).

templatestring

A template key from the library.

daysobject[]

Explicit training days; overrides the template's days.

Show properties

Array of object

labelstring

Day label.

slotsobject[]

Exercise slots in order.

Show properties

Array of object

musclestring

Muscle key.

exerciseIdstring

Exercise id from the library.

exerciseNamestring

Exercise name, matched against the library when no id is given.

notesstring

Free-text notes.

Responses

200

The created mesocycle.

object

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

Request body

Request

curl -X POST 'https://app.skcal.fit/api/training/mesocycles' \
  -H 'Cookie: __Secure-better-auth.session_token=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Winter bulk meso 1",
  "weeks": 5,
  "startDate": "2026-10-26",
  "template": "upper_lower_4",
  "days": [
    {
      "label": "Push",
      "slots": [
        {
          "muscle": "chest",
          "exerciseId": "barbell_bench_press"
        },
        {
          "muscle": "side_delts"
        }
      ]
    }
  ],
  "notes": "focus on chest and side delts"
}'

const response = await fetch("https://app.skcal.fit/api/training/mesocycles", {
  method: "POST",
  headers: {
    "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"Winter bulk meso 1\",\n  \"weeks\": 5,\n  \"startDate\": \"2026-10-26\",\n  \"template\": \"upper_lower_4\",\n  \"days\": [\n    {\n      \"label\": \"Push\",\n      \"slots\": [\n        {\n          \"muscle\": \"chest\",\n          \"exerciseId\": \"barbell_bench_press\"\n        },\n        {\n          \"muscle\": \"side_delts\"\n        }\n      ]\n    }\n  ],\n  \"notes\": \"focus on chest and side delts\"\n}"
});

import requests

response = requests.post(
    "https://app.skcal.fit/api/training/mesocycles",
    headers={
        "Cookie": "__Secure-better-auth.session_token=YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"Winter bulk meso 1\",\n  \"weeks\": 5,\n  \"startDate\": \"2026-10-26\",\n  \"template\": \"upper_lower_4\",\n  \"days\": [\n    {\n      \"label\": \"Push\",\n      \"slots\": [\n        {\n          \"muscle\": \"chest\",\n          \"exerciseId\": \"barbell_bench_press\"\n        },\n        {\n          \"muscle\": \"side_delts\"\n        }\n      ]\n    }\n  ],\n  \"notes\": \"focus on chest and side delts\"\n}",
)

Response

{
  "ok": true,
  "week": 2,
  "day": 1,
  "exerciseName": "Barbell Bench Press",
  "muscle": "chest"
}

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