Korzystanie z API

Wszystkie aplikacje Kombine korzystają z jednego REST API. Z osobistym tokenem dostępu twoje własne narzędzia też mogą z niego korzystać. Wszystko, co tu opisano, działa z curl i jq.

Bazowy URL: https://api.kombine.dev/v1
Uwierzytelnianie: wysyłaj token jako Authorization: Bearer kmb_pat_…
Format: JSON na wejściu i na wyjściu. Czas w formacie ISO 8601 (2026-10-23T09:00:00Z).
Pełna dokumentacja: specyfikacja OpenAPI opisuje każdy endpoint i każde pole. Wklej ją do dowolnej przeglądarki OpenAPI albo przekaż swojemu agentowi AI.

Skonfiguruj powłokę raz:

export KOMBINE_TOKEN='kmb_pat_…'
export API='https://api.kombine.dev/v1'
k() { curl -sS -H "Authorization: Bearer $KOMBINE_TOKEN" -H 'Content-Type: application/json' "$@"; }

Poniższe przykłady korzystają z tej funkcji pomocniczej k.

Zadania

Do wyświetlania listy potrzebujesz uprawnienia tasks: Read, a do zmian Read & write.

Lista zadań. Wyniki są stronicowane i trafiają do data, razem z total, limit (domyślnie 200, maks. 500) i offset:

k "$API/tasks?limit=500" | jq '.data[] | {title, status, priority, due_date}'

Serwer nie filtruje po statusie ani dacie, więc filtruj przez jq. Otwarte zadania z terminem na dziś lub wcześniej:

today=$(date +%F)
k "$API/tasks?limit=500" | jq -r --arg d "$today" '
  .data[] | select(.status != "DONE" and .is_archived == false and .due_date != null and .due_date[0:10] <= $d)
  | "\(.priority // "-")\t\(.title)"'

Dodawanie zadania. id zadania (dowolny UUID) wybiera twoje narzędzie, tak samo jak robią to aplikacje. Dzięki temu ponawianie żądań jest bezpieczne: dwukrotne wysłanie tego samego id nie utworzy dwóch zadań.

k -X POST "$API/tasks" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" '{
  id: $id,
  title: "Renew passport",
  priority: "HIGH",
  due_date: "2026-11-01T00:00:00Z",
  due_date_has_time: false,
  tags: ["errands"]
}')"

priority: LOW, MEDIUM lub HIGH (pomiń, jeśli bez priorytetu)
status: TODO (domyślnie), IN_PROGRESS lub DONE
due_date_has_time: false oznacza „termin na ten dzień”, bez konkretnej godziny

Zmiana zadania. PUT zmienia tylko pola, które wyślesz. Oznaczenie zadania jako wykonanego:

k -X PUT "$API/tasks/$TASK_ID" -d '{"status":"DONE"}'

Ukończenie zadania przez API liczy się tak samo jak w aplikacjach: trafia do twoich statystyk, a zadanie cykliczne przesuwa się na kolejny termin.

Sesje skupienia

Potrzebujesz uprawnienia sessions: Read & write. Zapisz sesję, którą odbyłeś gdzie indziej (spotkanie, bieganie, czas mierzony w innej aplikacji):

k -X POST "$API/sessions" -d "$(jq -n --arg id "$(uuidgen | tr A-Z a-z)" '{
  id: $id,
  mode: "POMODORO",
  started_at: "2026-10-23T07:00:00Z",
  ended_at: "2026-10-23T07:25:00Z",
  duration_ms: 1500000,
  note: "Pairing on the importer"
}')"

mode to POMODORO, FLOW lub ADAPTIVE. Dodaj task_id albo activity_id, żeby ją oznaczyć. Listę swoich aktywności pobierzesz przez k "$API/activities" | jq '.data[] | {id, name}'.

Timer

Potrzebujesz uprawnienia timer: Read. Sprawdź, co działa na którymkolwiek z twoich urządzeń:

k "$API/timer/state" | jq '{status, mode, is_break, started_at, elapsed_ms, task_id}'

Pusta odpowiedź (204) oznacza, że żaden timer nie działa.

Nie zalecamy uruchamiania ani zatrzymywania timera ze skryptu. Sesję zapisuje tylko aplikacja, w której działał timer, więc timer uruchomiony przez API nie zostawi po sobie sesji. Żeby zapisać czas, dodaj sesję (zobacz Sesje skupienia powyżej).

Statystyki

Potrzebujesz uprawnienia stats: Read.

k "$API/stats/all-time" | jq '{totalFocusSessions, hours: ((.totalFocusSeconds // 0) / 3600 | floor), longestStreakLength}'
k "$API/daily-snapshots?from=2026-10-01&to=2026-10-31" | jq '.snapshots[] | {date, sessions_completed, achieved}'

Statystyki z całego okresu są liczone w tle. Na zupełnie nowym koncie stats/all-time zwraca 404 („No stats available yet”), dopóki nie zostaną policzone po raz pierwszy.

Błędy

Błędy zwracane są jako JSON z polem error_code, po którym możesz je rozpoznawać, na przykład:

{ "title": "Forbidden", "status": 403, "detail": "Personal access token does not permit this route", "error_code": 1014 }

Status	`error_code`	Znaczenie	Co zrobić
400	5001, 5002	Brakuje pola lub jest nieprawidłowe; `errors` mówi, którego	Popraw żądanie
401	1013	Token wygasł	Utwórz nowy token
401	1011	Token unieważniony	Utwórz nowy token
401	1004	Token nierozpoznany	Sprawdź, czy skopiowałeś go w całości
403	1014	Uprawnienia tokena tego nie obejmują	Utwórz token z odpowiednimi uprawnieniami
409	4003	To `id` jest już zajęte	Przy ponowieniu możesz to zignorować
409	4010	Ten `external_ref` jest już użyty	Zobacz Przepływy pracy
429	6001	Za dużo żądań	Odczekaj `Retry-After` sekund

GET /v1/error-codes zwraca pełną listę (bez tokena).

Limity

Każdy token może wysłać 60 żądań na minutę, z krótkimi skokami do 20 naraz. Po przekroczeniu limitu dostaniesz 429 z nagłówkiem Retry-After. Nie wpływa to na inne tokeny ani na twoje aplikacje.