Getting started

Build on Gravl.

Your training data, programmable. A versioned, scoped, read-only REST API over workouts, records, measurements and stats — plus an MCP server that lets AI assistants act on your Gravl account.

Personal tokens

Building something for yourself? Create a token from your own account and start reading your data in one request.

OAuth apps

Building for other Gravl users? Request access with OAuth 2.0 — users grant only the scopes you ask for.

Gravl MCP

Connect Claude or any MCP client to your account: log workouts and manage your training from a conversation.

The API at a glance


Base URL	`https://api.gravl.ai`
Version	All endpoints live under `/api/v1` — breaking changes only ever ship as a new version.
Format	JSON in and out; UTF-8; dates are UTC ISO 8601.
Auth	Bearer tokens (`gat_…`) from a personal token or an OAuth grant.
Access	Read-only today. Write scopes will be introduced deliberately, not implicitly.
CORS	Open (non-credentialed) on `/api/v1` and `/oauth` — browser apps can call the API directly.
Status	Beta — the surface is stable, but registration for OAuth apps is manual.

Your first request

Grab a personal token and you’re one curl away from your training history:

List your workouts

curl "https://api.gravl.ai/api/v1/workouts?page=1&pageSize=2" \
  -H "Authorization: Bearer gat_…"

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Push Day",
      "notes": null,
      "startDate": "2026-07-12T17:03:00Z",
      "endDate": "2026-07-12T18:05:00Z",
      "durationMinutes": 62,
      "type": "custom",
      "volume": 24150,
      "calories": 410,
      "personalRecordCount": 1,
      "exerciseCount": 6
    }
  ],
  "pageNumber": 1,
  "totalPages": 87,
  "totalCount": 174,
  "hasPreviousPage": false,
  "hasNextPage": true
}

Every token — personal or OAuth — is bound to one user and a set of scopes. There is no scope that grants access to anyone else’s data.

Questions or ideas?

The developer platform is young and shaped by what people build. For OAuth app registration, questions, or feature requests, email developers@gravl.ai.