Reference

Konvence a chyby

Pravidla, která platí napříč všemi endpointy, aby ses je musel učit jen jednou.

Stránkování

Endpointy se seznamy přijímají query parametry page (od 1) a pageSize (1–100, výchozí 30) a výsledky balí do jedné obálky:

{
  "items": [ … ],
  "pageNumber": 2,
  "totalPages": 9,
  "totalCount": 174,
  "hasPreviousPage": true,
  "hasNextPage": true
}

Hodnoty enumů jsou vždy řetězce v camelCase, nikdy celá čísla: "pounds", "kilometers", "oneRepMax", "chest", "normal". S neznámými hodnotami enumů počítej jako s dopředně kompatibilními: nové můžou přibýt i bez změny verze.

Jednotky

Veličina	Jednotka
Váha (série, rekordy)	Libry
Vzdálenost	Metry
Délka série / rekordu	Sekundy
Délka tréninku	Minuty (durationMinutes)
Tělesné míry	Systém jednotek podle weightUnit daného záznamu (palce s librami, centimetry s kilogramy)

Preferované zobrazovací jednotky uživatele najdeš na /api/v1/user; převáděj až na okraji své aplikace, ne v úložišti.

Identifikátory

Uživatelská data (tréninky, šablony, splity, míry): stabilní GUID
Katalogová data (cviky, vybavení): stabilní celočíselná id sdílená s aplikací Gravl
Uživatel: neprůhledné řetězcové id, stabilní napříč všemi endpointy a tokeny

Datumy

Všechny časové údaje jsou UTC, ISO 8601 (2026-07-12T17:03:00Z). Filtry rozsahu dat (startDate, endDate) jsou včetně krajních hodnot.

Rate limity

Oblast	Limit	Klíčováno podle
`/api/v1/*`	100 requestů / 15 min	aplikace + uživatel
`/oauth/*`	10 requestů / min	IP adresa

Překročení limitu vrací 429, a když je k dispozici, i hlavičku Retry-After. Ustupuj exponenciálně a nedělej polling; většina osobních dat se mění lidským tempem.

Chyby

Status	Kdy	Tělo
401	Chybějící, poškozený, expirovaný nebo zneplatněný token; pozastavená aplikace	Prázdné (výzva WWW-Authenticate)
403	Platný token, chybějící scope	Problem details s názvem chybějícího scope
404	Zdroj neexistuje, nebo patří jinému uživateli	Problem details
429	Překročený rate limit	Prázdné; hlavička Retry-After
400	Selhání validace (špatná velikost stránky, poškozené parametry)	Problem details s chybami jednotlivých polí

Problem details (RFC 7807)

{
  "status": 403,
  "title": "Missing scope",
  "detail": "This authorization is missing the 'measurements:read' scope."
}