Shape REST API

GET/activities

List activities in a date range. Returns { activities, total, limit, offset }.

Query parameters (all optional)

GET /activities?from=2026-03-01&to=2026-03-31

GET/activities/:id

Get a single activity by ID. Returns { activity }.

GET/activities/:id/details

Recorded time-series for a completed activity: heart rate, pace, cadence, power, elevation and GPS as parallel arrays indexed against time, plus lap splits and time in zone. Optional channels, points (10-2000, default chosen by duration), includeLaps and includeZones params. Only activities recorded by a connected device have this; otherwise returns 404 with a reason code and message.

POST/activities

Create an activity. Returns { activity } with status 201.

Required fields

Optional fields

PATCH/activities/:id

Update an activity. Send only the fields you want to change. Same fields as create, all optional. Returns { activity }.

DELETE/activities/:id

Delete an activity. Returns { deleted: true }.

POST/activities/batch

Create up to 100 activities in one request. Returns { activities } with status 201.

{ "activities": [{ date, title, sportType, ... }, ...] }

PATCH/activities/batch

Update up to 100 activities in one request. Each object must include id plus the fields to change. Returns { updated }.

{ "activities": [{ "id": "id1", "completed": true }, ...] }

DELETE/activities/batch

Delete up to 100 activities by ID. Returns { deleted }.

{ "ids": ["id1", "id2", ...] }

POST/activities/pair

Pair a completed activity with a planned one. The completed row gets plannedActivityId set; the planned row gets completedActivityId set. After pairing, the planned activity is hidden from the default list view. Returns { paired: true, completedActivityId, plannedActivityId }.

{ "completedActivityId": "id1", "plannedActivityId": "id2" }

The completed activity must have completed: true and the planned activity must have completed: false. 400 otherwise. Idempotent when the same pair is sent twice. Fails with 409 if either side is already paired with a different activity. Call /activities/unpair first.

POST/activities/unpair

Remove the pairing between an activity and its partner. Pass either side; both rows are unlinked. If the partner row no longer exists (e.g. it was deleted), only this side is cleared and partnerId is returned as null. Returns { unpaired: true, activityId, partnerId }.

{ "activityId": "id1" }

GET/health-metrics

List daily health metrics (sleep, HRV, resting heart rate, stress, body battery, VO2max, body composition, steps), merged across your connected sources into one record per day. Returns { days, total }.

Query parameters (all optional)

GET /health-metrics?from=2026-07-01&metrics=restingHR,sleepScore

Response day object

{
  "date": "2026-07-10",
  "values": { "restingHR": 42, "sleepDurationSec": 28800, "steps": 6941 },
  "sources": { "restingHR": "garmin", "sleepDurationSec": "garmin", "steps": "garmin" },
  "hrvMethod": "rmssd",
  "sleepScoreQualifier": "good"
}

values holds the chosen number per metric and sources records which provider it came from. Raw provider payloads are never returned.

GET/training-status

Readiness, training load, and what the plan does to it, in one call. Use it to ask whether you should train hard today, whether you are ramping too fast, why readiness is low, or what this week's plan does to your load.

Query parameters (all optional)

GET /training-status?from=2026-07-15&to=2026-08-15

Limit the response

By default you get every block. Use include to get only the ones you need: include=load,series drops most of the payload and skips reading body metrics.

A block you leave out is missing from the response, not null. readinessUnavailable: null means nothing was wrong, and a missing key means you didn’t ask for it. An unknown name returns a 400. include never changes the values that come back.

Response

{
  "date": "2026-08-15",
  "dateInferred": false,
  "readiness": {
    "basis": "current",
    "score": 74,
    "band": "high",
    "drivers": [
      { "key": "restingHR", "label": "Resting HR", "value": 42, "baseline": 42.7,
        "z": 0.5, "weight": 0.3, "unit": "bpm", "source": "garmin" }
    ]
  },
  "readinessUnavailable": null,
  "load": { "fitness": 61.2, "fatigue": 74.8, "form": -13.6, "ratio": 1.22, "band": "safe" },
  "loadUnavailable": null,
  "loadCoverage": { "withLoad": 38, "total": 40 },
  "projection": { "date": "2026-08-19", "ratio": 1.44 },
  "providerScores": [
    { "source": "garmin", "key": "sleepScore", "label": "Sleep score", "value": 81, "scale": "0-100" }
  ]
}

Two readiness numbers, deliberately

The snapshot includes training already completed today, so it falls through the day as you train: that is the “can I do more right now” number. Every day in series is morning readiness and never includes it, because a trend carrying it would just redraw your training schedule. So a past day’s series score is how you woke up, not how the day ended, and the two can differ for the same date. Each says which it is in basis.

When there is no score

readiness is null and readinessUnavailable says why, because the fix differs completely: insufficient_baseline means wait, no_readings_today means sync your watch, and no_body_metrics means connect one. loadUnavailable does the same for load, separating no_workouts from no_load_data, which are workouts that could carry load and do not.

dateInferred is true when we had to guess which calendar day is yours. Your timezone is recorded when you open the app; until then the day is inferred from your most recent data and clamped to within a day of UTC.

The week ahead, and a longer range

With no dates, series is today plus the next 7 days of fitness, fatigue, form and ratio. No readiness: that cannot be projected. projection is the peak of that week.

Passing from and to replaces that strip with the requested history: one entry per day, including morning readiness and its drivers. Future days still carry projected: true and no readiness. hasPlannedLoad separates a day a planned workout actually contributes load to from the rest days where the curves merely decay.

This returns the plan’s consequence, not the plan. For what is actually on the calendar, call /activities.