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.