Référence
Conventions et erreurs
Les règles valables sur tous les endpoints, pour ne les apprendre qu’une seule fois.
Pagination
Les endpoints de liste prennent page (commence à 1) et pageSize (1–100, 30 par défaut) en paramètres de requête et enveloppent les résultats dans une enveloppe unique :
{
"items": [ … ],
"pageNumber": 2,
"totalPages": 9,
"totalCount": 174,
"hasPreviousPage": true,
"hasNextPage": true
}Les enums sont des chaînes camelCase
Les valeurs d’enum sont toujours des chaînes en camelCase, jamais des entiers : "pounds", "kilometers", "oneRepMax", "chest", "normal". Traite les valeurs d’enum inconnues avec tolérance : de nouvelles peuvent apparaître sans changement de version.
Unités
| Mesure | Unité |
|---|---|
| Poids (séries, records) | Livres |
| Distance | Mètres |
| Durée de série / record | Secondes |
| Durée de séance | Minutes (durationMinutes) |
| Mensurations | Le système d’unités du weightUnit de l’entrée (pouces avec les livres, centimètres avec les kilogrammes) |
Les unités d’affichage préférées de l’utilisateur sont sur /api/v1/user : convertis à la frontière de ton app, pas dans ton stockage.
Identifiants
- Données utilisateur (séances, templates, splits, mensurations) : des GUID stables
- Données de catalogue (exercices, matériel) : des ids entiers stables partagés avec l’app Gravl
- L’utilisateur : un id chaîne opaque, stable sur tous les endpoints et tous les tokens
Dates
Tous les timestamps sont en UTC, ISO 8601 (2026-07-12T17:03:00Z). Les filtres par plage de dates (startDate, endDate) sont inclusifs.
Rate limits
| Surface | Limite | Clé |
|---|---|---|
/api/v1/* | 100 requêtes / 15 min | app + utilisateur |
/oauth/* | 10 requêtes / min | adresse IP |
Dépasser une limite renvoie 429 avec un header Retry-After quand il est disponible. Applique un backoff exponentiel et évite le polling : la plupart des données personnelles changent à vitesse humaine.
Erreurs
| Statut | Quand | Corps |
|---|---|---|
| 401 | Token manquant, malformé, expiré ou révoqué ; app suspendue | Vide (challenge WWW-Authenticate) |
| 403 | Token valide, scope manquant | Problem details, avec le scope manquant nommé |
| 404 | La ressource n’existe pas, ou appartient à un autre utilisateur | Problem details |
| 429 | Rate limit dépassée | Vide ; header Retry-After |
| 400 | Échec de validation (mauvaise taille de page, paramètres malformés) | Problem details, avec les erreurs par champ |
{
"status": 403,
"title": "Missing scope",
"detail": "This authorization is missing the 'measurements:read' scope."
}Note la règle du 404 pour les données d’autrui : demander la séance d’un autre utilisateur par id renvoie 404, pas 403. L’API ne confirme jamais l’existence de données que tu ne peux pas voir.