# Calcul Allure: API and MCP

> Full reference of the public JSON API and of the MCP server of https://calcul-allure.com: endpoints, parameters, responses, error contract and tools.

Navigation index: https://calcul-allure.com/llms.txt
Everything in one file: https://calcul-allure.com/llms-full.txt

## API for developers and agents

All endpoints are GET, JSON, no authentication, no API key, no rate limit announced, CORS open (`Access-Control-Allow-Origin: *`), responses cached 60 seconds (`Cache-Control: public, max-age=60`).

Every operation is read-only and idempotent, so retries are safe. Errors are always JSON, never HTML: 400 for a missing or invalid parameter, 404 for an unknown /api/* path, 405 for a method other than GET, HEAD or OPTIONS (with an `Allow` header). The body carries `error` (English, historical), `code` (stable snake_case: missing_parameter, invalid_distance, invalid_time, not_found, method_not_allowed), `message` (French), `hint` and `docs`. The API is unversioned: /api/* is the stable surface, changes are additive, any breaking change is announced 6 months ahead with `Deprecation` and `Sunset` headers.

- Human-readable documentation (French): https://calcul-allure.com/api
- OpenAPI 3.1 specification: https://calcul-allure.com/openapi.json

- GET https://calcul-allure.com/api/pace : pace, speed and splits for a distance and a time.
- GET https://calcul-allure.com/api/plan : personalised training plan.
- GET https://calcul-allure.com/api/status : `{ "status": "running", "version": "1.0.0", "timestamp": "..." }`.
- GET https://calcul-allure.com/health : `{ "status": "ok" }`.
- GET /api/calculer : legacy URL, permanent redirect (301) to /api/pace with the same query string.

### GET /api/pace

Parameters:
- `distance` (required): kilometres as a number (`21.0975`, `15`, `0.4`) or an alias: `5km`, `10km`, `semi`, `semi-marathon`, `marathon`, `100m`, `200m`, `400m`, `800m`, `1500m`, `3000m`, `5000m`, `10000m`. Any positive number works, so custom distances are supported.
- `time` (required): total time as integer seconds (`6300`), `1h45m00s`, `1h45`, `1:45:00`, `50m00s` or `50:00`. `temps` is accepted as a legacy alias of `time`.

Response:
```
{
  "distance_km": 21.0975,
  "distance_label": "Semi-marathon",
  "time": "1h45'00\"",
  "time_seconds": 6300,
  "pace": "4'59\"",              // min'sec" per km
  "pace_seconds_per_km": 298.613581,
  "speed": "12.06 km/h",
  "speed_kmh": 12.06,
  "splits": [ { "km": 1, "label": "1 km", "time": "4'59\"" }, ... ]
}
```
Splits are given at 1 km, 5 km, 10 km, half marathon and marathon points that fall inside the distance, plus the finish.

Examples:
- https://calcul-allure.com/api/pace?distance=semi&time=6300 : pace 4'59"/km, 12.06 km/h
- https://calcul-allure.com/api/pace?distance=10km&time=50m00s : pace 5'00"/km, 12.0 km/h
- https://calcul-allure.com/api/pace?distance=marathon&time=3h30m00s : pace 4'59"/km (298.6 s/km), 12.06 km/h
- https://calcul-allure.com/api/pace?distance=0.4&time=60 : 400 m in 60 s, pace 2'30"/km, 24 km/h

### GET /api/plan

Parameters:
- `distance` (required): `5km`, `10km`, `semi` (or `semi-marathon`), `marathon`. Track spellings `5000m` and `10000m` map to 5 km and 10 km.
- `time` (required): target race time, same formats as /api/pace.
- `age` (optional, 1-119): 40 and over, recovery times +10 % and session volume x0.95; 50 and over, recovery +20 % and volume x0.85.
- `sessions` (optional, 2-6, default 3): sessions per week. A 4th session is added for every distance; a 5th and 6th only for half marathon and marathon. Out-of-range values fall back to 3.
- `weeks` (optional): total weeks, clamped to the valid range of the distance. 5 km and 10 km: 6 to 12 (default 8). Half marathon: 8 to 20 (default 12). Marathon: 12 to 24 (default 16).
- `vo2max` (optional, 10-100): switches the pace zones to VO2max-based percentages (see below).
- `previous_time` (optional): a previous race time on the same distance; the gap to the target reweights the plan phases (large gap: more base work; small gap: more intensity).

Level, detected from the target time:
- advanced: 5 km <= 22 min, 10 km <= 45 min, half <= 1h45, marathon <= 3h30
- intermediate: 5 km <= 35 min, 10 km <= 70 min, half <= 2h30, marathon <= 5h
- beginner: slower than intermediate

Training paces without VO2max (seconds per km, from the race pace):
- race: target pace
- easy: race + 90 s/km
- tempo: race + 15 s/km (lactate threshold)
- interval: race - 15 s/km, never faster than 2'30"/km
- long_run: race + 60 s/km

Training paces with VO2max: VMA (km/h) = VO2max / 3.5, VMA pace = 3600 / VMA; easy = VMA pace / 0.65, tempo = VMA pace / 0.82, interval = VMA pace / 0.95, long_run = VMA pace / 0.72.

Response:
```
{
  "distance_km": 21.0975,
  "distance_label": "Semi-marathon",
  "target_time": "1h45'00\"",
  "target_time_seconds": 6300,
  "level": "beginner" | "intermediate" | "advanced",
  "paces": {
    "race":     { "display": "4'59\"/km", "seconds_per_km": 298.613581 },
    "easy":     { ... }, "tempo": { ... }, "interval": { ... }, "long_run": { ... }
  },
  "total_weeks": 12,
  "sessions_per_week": 3,
  "weeks": [
    {
      "week": 1,
      "phase": "Base" | "Development" | "Intensity" | "Taper" | "Race Prep" | "Race",
      "sessions": [
        { "type": "easy" | "tempo" | "interval" | "long_run" | "race",
          "title": "...",          // French session name
          "description": "..." }   // French session detail with paces
      ]
    }
  ],
  "personalization": {
    "age": number | null, "sessions_per_week": number, "total_weeks": number,
    "uses_vo2max": boolean, "vo2max": number | null,
    "previous_time_seconds": number | null, "gap_to_target_percent": number | null
  }
}
```

Examples:
- https://calcul-allure.com/api/plan?distance=semi&time=6300 : 12-week half marathon plan, intermediate, 3 sessions/week
- https://calcul-allure.com/api/plan?distance=marathon&time=3h30m00s&sessions=4&weeks=16&age=45 : 16-week marathon plan, advanced, 4 sessions/week, age-adjusted recovery
- https://calcul-allure.com/api/plan?distance=10km&time=50m00s&vo2max=52 : 8-week 10 km plan with VO2max-based paces
- https://calcul-allure.com/api/plan?distance=5km&time=25m00s&sessions=3&weeks=8 : 8-week 5 km plan, intermediate

Session titles and descriptions are in French; keys, phase names and level names are in English.

## MCP server

- MCP server (Model Context Protocol): POST https://calcul-allure.com/mcp, Streamable HTTP transport, protocol version 2025-06-18, stateless (no session id), no authentication, CORS open.
- Tools: `compute_pace` (a distance and a time, returns pace, speed and splits), `generate_training_plan` (5km, 10km, semi or marathon plus a target time, returns a week by week plan) and `get_site_guide` (the map of this documentation). All three are read only and idempotent.
- Server card: https://calcul-allure.com/.well-known/mcp/server-card.json. GET /mcp answers 405 on purpose: this server offers no SSE stream, send your JSON-RPC 2.0 messages by POST.

## Discovery files

- https://calcul-allure.com/api : human-readable documentation of the JSON API (French, HTML).
- https://calcul-allure.com/api/llms.txt : full reference of the JSON API and of the MCP server, for agents.
- https://calcul-allure.com/openapi.json : OpenAPI 3.1 specification, checked against the real logic at every build.
- https://calcul-allure.com/.well-known/api-catalog : API catalogue (RFC 9727 linkset).
- https://calcul-allure.com/.well-known/ai-catalog.json : AI resource catalogue (guides, corpus, endpoints).
- https://calcul-allure.com/.well-known/agent-skills/index.json : agent skills exposed by the site.
- https://calcul-allure.com/.well-known/mcp/server-card.json : MCP server card.