API Overview
The FitRepo API is a JSON REST API that powers both the web app and the MCP server. You can call it directly to build integrations or automate data access.
Base URL
Section titled “Base URL”https://mydatafor.lifeIf self-hosting, replace with your instance URL.
Authentication
Section titled “Authentication”Different route groups use different auth mechanisms:
| Route group | Auth mechanism |
|---|---|
/api/mcp/* (except keys) | MCP Bearer token (Authorization: Bearer <api-key>) |
POST/DELETE /api/mcp/keys | Supabase session cookie (web app login) |
/api/account/*, /api/settings, /api/connections/*, /api/backfill/*, /api/activities/*, /api/documents/* | Supabase session cookie |
/api/webhooks/wahoo | Per-user webhook token (encoded in the webhook URL) |
/api/health, /api/oauth/.* | Public or session-mediated (see individual endpoint docs) |
For direct API access to the MCP endpoints, generate an API key in Settings → MCP & API Keys and pass it as a Bearer token.
Response format
Section titled “Response format”All responses are JSON. Successful responses return HTTP 2xx. Errors return a JSON body:
{ "error": "Human-readable error message" }Common status codes:
| Code | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (missing or invalid API key) |
| 404 | Not found |
| 409 | Conflict (e.g. a push to that destination is already in progress) |
| 422 | Unprocessable (e.g. streams requested for an activity with no stored FIT file) |
| 429 | Too many requests (e.g. more than 5 imports started in an hour) |
| 502 | Upstream provider error (e.g. Intervals.icu rejected the request) |
| 503 | Service degraded (see /api/health) |
Pagination
Section titled “Pagination”List endpoints accept limit and offset query parameters. The activities endpoint defaults to limit=50 with a maximum of 200. Other list endpoints may differ — check the individual endpoint docs.
Date parameters
Section titled “Date parameters”Dates are accepted as YYYY-MM-DD strings. Timestamps are returned as ISO 8601 UTC strings (2025-03-15T07:30:00Z).
Endpoints
Section titled “Endpoints”| Method | Path | Description |
|---|---|---|
| GET | /api/health | Healthcheck |
| GET | /api/mcp/activities | List activities |
| GET | /api/mcp/activities/:id | Get activity |
| GET | /api/mcp/fitness | Fitness timeline (CTL/ATL/TSB) |
| GET | /api/mcp/best-efforts | All-time best efforts |
| GET | /api/mcp/wellness | Wellness log |
| GET | /api/mcp/thresholds | Threshold history |
| GET | /api/mcp/profile | Athlete profile |
| GET | /api/mcp/activities/:id/streams | Downsampled per-second streams (resolution, channels, startOffset, endOffset) |
| GET | /api/mcp/activities/:id/laps | Device laps and detected climbs (detectClimbs=false to skip) |
| POST | /api/mcp/planned-workouts | Push planned workouts to Intervals.icu ({ workouts, dryRun }) |
| GET | /api/mcp/planned-workouts | Read planned events (oldest, newest, onlyFitrepo, categories) |
| GET | /api/mcp/backfill | Import sources, latest activity, job status (jobIds, waitSeconds) |
| POST | /api/mcp/backfill | Start an import ({ source, from, to, force }) |
| GET | /api/mcp/documents | Coaching documents: ?active=1, ?id= / ?slug=, or list (?type=) |
| POST | /api/mcp/documents | Save a new document version ({ type, content, slug, name, activate, basedOn }) |
| POST | /api/mcp/documents/active | Make a document active ({ id } or { slug, type }) |
| POST | /api/mcp/keys | Generate API key |
| DELETE | /api/mcp/keys | Revoke API key |
| GET | /api/account/export | Export all data (JSON download) |
| DELETE | /api/account/delete | Delete account (GDPR erasure) |