Paggered Read API v1

Six GET routes, stable envelopes, opaque IDs, UTC ISO timestamps, and canonical metric storage units. Lists use cursor pagination and return at most ten items.

Download OpenAPI 3.1 YAML

Endpoints

GET

/api/v1/me

None

Display name, unit preference, and timezone.

GET

/api/v1/stats

None

This week, rolling 30 local days, and consecutive active weeks.

GET

/api/v1/workouts

limit=1-10, cursor

Completed workout summaries in stable newest-first order.

GET

/api/v1/workouts/{id}

Opaque workout id

Exercises, completed set performance, and historical PR indicators for one owned workout.

GET

/api/v1/saved-workouts

limit=1-10, cursor

Saved workout titles and exercise counts.

GET

/api/v1/saved-workouts/{id}

Opaque saved-workout id

Ordered exercises, sets, reps, and rest for one saved workout.

Response contract

Successful responses contain data and a top-level request_id.
Errors contain error.code, error.message, and error.request_id.
Every response includes Cache-Control: private, no-store and X-Request-Id.
Weights are kilograms, distance is metres, and duration is seconds.
Workout sets include records from the fixed weight, reps, set_volume, and estimated_1rm vocabulary. A label means the set beat every eligible set completed earlier for that exercise; later workouts do not erase the historical achievement.
Workout lists include completed sessions only and sort newest first with a stable ID tie-break.
List cursors are opaque. Pass next_cursor back unchanged; do not parse or construct it.

Personal-record semantics

Record indicators reuse Paggered's strength-set rules. Warmups, incomplete current sets, and structured drop sets without an eligible completed parent are excluded. Equal values do not create another record, and deterministic set order chooses one winner when sets in the same workout tie.

The values identify the heaviest weight, highest reps, largest single-set volume, and highest Epley estimated one-rep max. They are derived from the set performance already shared through the workouts scope and do not add another connection permission.

Stats semantics

The stats route counts completed workouts only. It resolves each workout's local date from its start time, falling back to creation time, in the profile's validated timezone.

An active week runs Monday to Sunday and needs at least one completed workout. A weekly streak remains current when the latest active week is this week or the immediately previous week, so it does not reset on Monday morning before a session has been logged.