Die API nutzen

Alle Kombine-Apps sprechen mit derselben REST-API. Mit einem persönlichen Zugriffstoken können auch deine eigenen Tools sie nutzen. Alles hier funktioniert mit curl und jq.

Basis-URL: https://api.kombine.dev/v1
Authentifizierung: Schick das Token als Authorization: Bearer kmb_pat_…
Format: JSON rein, JSON raus. Zeitangaben sind ISO 8601 (2026-10-23T09:00:00Z).
Vollständige Referenz: Die OpenAPI-Spezifikation listet jeden Endpunkt und jedes Feld auf. Füg sie in einen beliebigen OpenAPI-Viewer ein oder gib sie deinem KI-Agenten.

Richte deine Shell einmal ein:

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' "$@"; }

Die Beispiele unten nutzen diesen k-Helfer.

Aufgaben

Braucht tasks: Read zum Auflisten und Read & write zum Ändern.

Aufgaben auflisten. Die Ergebnisse kommen seitenweise unter data, mit total, limit (Standard 200, maximal 500) und offset:

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

Es gibt keinen serverseitigen Filter für Status oder Datum, also filterst du mit jq. Offene Aufgaben, die heute oder früher fällig sind:

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)"'

Aufgabe hinzufügen. Dein Tool wählt die id der Aufgabe (eine beliebige UUID), genau wie die Apps. Dadurch sind Wiederholungen sicher: Wenn du dieselbe id zweimal schickst, entstehen nicht zwei Aufgaben.

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 oder HIGH (weglassen für keine)
status: TODO (Standard), IN_PROGRESS oder DONE
due_date_has_time: false bedeutet „an diesem Tag fällig“, ohne Uhrzeit

Aufgabe ändern. PUT ändert nur die Felder, die du mitschickst. So markierst du eine Aufgabe als erledigt:

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

Eine Aufgabe über die API abzuschließen zählt genauso wie in den Apps: Es wird für deine Statistiken erfasst, und eine wiederkehrende Aufgabe springt auf ihren nächsten Termin.

Fokus-Sessions

Braucht sessions: Read & write. Trag eine Session ein, die du woanders gemacht hast (ein Meeting, ein Lauf, Zeit aus einer anderen App):

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 ist POMODORO, FLOW oder ADAPTIVE. Füg task_id oder activity_id hinzu, um sie zuzuordnen. Deine Aktivitäten listest du mit k "$API/activities" | jq '.data[] | {id, name}' auf.

Timer

Braucht timer: Read. Sieh nach, was auf einem deiner Geräte läuft:

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

Eine leere Antwort (204) bedeutet, dass kein Timer läuft.

Den Timer per Skript zu starten oder zu stoppen ist nicht empfehlenswert. Eine Session wird nur von der App gespeichert, in der der Timer lief, also hinterlässt ein über die API gestarteter Timer keine Session. Wenn du Zeit erfassen willst, trag stattdessen eine Session ein (siehe Fokus-Sessions oben).

Statistiken

Braucht 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}'

Die Gesamtstatistiken werden im Hintergrund berechnet. Bei einem ganz neuen Konto antwortet stats/all-time mit 404 („No stats available yet“), bis sie zum ersten Mal berechnet wurden.

Fehler

Fehler kommen als JSON mit einem error_code, auf den du prüfen kannst, zum Beispiel:

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

Status	`error_code`	Bedeutung	Was tun
400	5001, 5002	Ein Feld fehlt oder ist ungültig; `errors` sagt, welches	Anfrage korrigieren
401	1013	Token abgelaufen	Neues Token erstellen
401	1011	Token widerrufen	Neues Token erstellen
401	1004	Token nicht erkannt	Prüfen, ob du es vollständig kopiert hast
403	1014	Die Berechtigungen des Tokens reichen dafür nicht	Token mit den passenden Berechtigungen erstellen
409	4003	Diese `id` ist schon vergeben	Bei einer Wiederholung kannst du das ignorieren
409	4010	Diese `external_ref` wird schon verwendet	Siehe Workflows
429	6001	Zu viele Anfragen	`Retry-After` Sekunden warten

GET /v1/error-codes listet alle auf (kein Token nötig).

Limits

Jedes Token hat 60 Anfragen pro Minute, mit kurzen Spitzen von bis zu 20. Darüber hinaus bekommst du 429 mit einem Retry-After-Header. Andere Tokens und deine Apps sind davon nicht betroffen.