API reference

Everything the app does goes through the JSON API under /api — and you can use it too. Interactive OpenAPI docs live at /api/docs on your instance; this page is the practical quickstart.

Authentication

Create a token in Settings → API → Create API token. Two scopes:

• Full access — everything your account can do.
• Read-only — GETs only; safe for dashboards and analysis scripts.

export FORGE=https://forge.example.com
export TOKEN=forge_pat_...

curl -H "Authorization: Bearer $TOKEN" $FORGE/api/workouts

Tokens are shown once at creation and can be revoked any time.

Log a workout in one call

POST /api/workouts/log creates a complete, finished workout. Exercises resolve by exercise_id or by name; unknown names create custom exercises. PRs recompute chronologically, so backdating works.

{
  "name": "Push Day",
  "started_at": "2026-07-17T17:30:00Z",
  "duration_seconds": 3600,
  "exercises": [
    { "name": "Bench Press", "sets": [
      {"weight": 60, "reps": 10, "is_warmup": true},
      {"weight": 80, "reps": 8},
      {"weight": 80, "reps": 7, "set_type": "failure", "rpe": 9}
    ]}
  ]
}

The surface