The FlowRoll API

Create an API key in Settings → Developer and send it as a bearer token. Keys only access your own data — sessions shared with you by others are not exposed. Rate limit: 1,000 requests per key per day.

curl https://www.flowroll.xyz/api/v1/me \
  -H "Authorization: Bearer frk_YOUR_KEY"

Your profile: name, belt, stripes, home gym.

{
  "profile": {
    "id": "…", "display_name": "…",
    "first_name": "…", "last_name": "…",
    "belt": "blue", "stripes": 2,
    "home_gym_name": "…", "created_at": "…"
  }
}

Your sessions, newest first. Optional query params: from / to (YYYY-MM-DD), limit (max 200), offset.

curl "https://www.flowroll.xyz/api/v1/sessions?from=2026-06-01&limit=10" \
  -H "Authorization: Bearer frk_YOUR_KEY"

Each session has trained_on, duration_min, rounds, gym, feel (1–5), subs_hit, subs_caught_in, partners, drilled, note, media_urls.

Fetch one by id: GET /api/v1/sessions/:id

Log a session. Requires a key created with allow writes. Required: trained_on, duration_min.

curl -X POST https://www.flowroll.xyz/api/v1/sessions \
  -H "Authorization: Bearer frk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trained_on": "2026-07-14",
    "duration_min": 90,
    "rounds": 6,
    "feel": 4,
    "subs_hit": ["armbar"],
    "note": "logged via the API"
  }'

Lifetime totals, current streak, per-submission scorecard, and weekly volume — the same numbers as your dashboard.

{
  "totals": { "total_sessions": 42, "total_min": 3780, … },
  "streak": 3,
  "submissions": [ { "name": "armbar", "hit": 9, "caught": 2, … } ],
  "weekly_volume": [ { "week_start": "2026-07-06", "mat_min": 270, … } ]
}

API use is governed by the Terms of Service: keys are personal and access only your own data — keep them secret, respect the rate limit, don't use the API to circumvent app privacy rules, and don't resell access. Abused keys get revoked.

JSON with an error field. 401 missing or invalid key · 403 missing scope · 429 daily limit reached · 400 bad input. Revoke a leaked key instantly in Settings.