Referencja

Konwencje i błędy

Zasady wspólne dla każdego endpointu, żebyś musiał nauczyć się ich tylko raz.

Paginacja

Endpointy list przyjmują parametry zapytania page (liczony od 1) i pageSize (1–100, domyślnie 30) i opakowują wyniki w jedną kopertę:

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

Wartości enumów są zawsze łańcuchami w camelCase, nigdy liczbami: "pounds", "kilometers", "oneRepMax", "chest", "normal". Nieznane wartości enumów traktuj jako zgodne w przód: nowe mogą pojawić się bez zmiany wersji.

Jednostki

Wielkość	Jednostka
Ciężar (serie, rekordy)	Funty
Dystans	Metry
Czas trwania serii / rekordu	Sekundy
Czas trwania treningu	Minuty (durationMinutes)
Pomiary ciała	System jednostek z pola weightUnit wpisu (cale przy funtach, centymetry przy kilogramach)

Preferowane jednostki wyświetlania użytkownika znajdziesz pod /api/v1/user. Konwertuj na brzegu swojej aplikacji, nie w miejscu przechowywania danych.

Identyfikatory

Dane użytkownika (treningi, szablony, splity, pomiary): stałe GUID-y
Dane katalogowe (ćwiczenia, sprzęt): stałe liczbowe id, wspólne z aplikacją Gravl
Użytkownik: nieprzezroczyste łańcuchowe id, stałe we wszystkich endpointach i tokenach

Daty

Wszystkie znaczniki czasu są w UTC, ISO 8601 (2026-07-12T17:03:00Z). Filtry zakresów dat (startDate, endDate) są włączne.

Limity żądań

Powierzchnia	Limit	Kluczowane po
`/api/v1/*`	100 żądań / 15 min	aplikacja + użytkownik
`/oauth/*`	10 żądań / min	adres IP

Przekroczenie limitu zwraca 429, a gdy to możliwe także nagłówek Retry-After. Wycofuj się wykładniczo i nie odpytuj w pętli; większość danych osobistych zmienia się w ludzkim tempie.

Błędy

Status	Kiedy	Treść
401	Brakujący, źle sformułowany, wygasły lub unieważniony token; zawieszona aplikacja	Pusta (nagłówek WWW-Authenticate)
403	Poprawny token, brak scope’a	Problem details z nazwą brakującego scope’a
404	Zasób nie istnieje lub należy do innego użytkownika	Problem details
429	Przekroczony limit żądań	Pusta; nagłówek Retry-After
400	Błąd walidacji (zły rozmiar strony, źle sformułowane parametry)	Problem details z błędami pól

Problem details (RFC 7807)

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