REST-API

Die kostenlose API — für Home Assistant, eigene Skripte oder jede Wallbox.

Kilonaut hat eine schlanke REST-API, mit der du Ladevorgänge und Kilometerstände programmatisch sendest. Sie ist dauerhaft kostenlos und braucht nur einen persönlichen Token, den du in den Einstellungen unter „API & Home Assistant" erzeugst.

Basis-URL & Authentifizierung

Alle Endpunkte liegen unter der Basis-URL und erwarten den Token als Bearer-Header. Requests und Responses sind JSON.

Base URL:  https://kilonaut.de/api/v1

Authorization: Bearer <dein-token>
Content-Type:  application/json

Endpunkte

{
  "ok": true,
  "user": { "email": "you@example.com", "plan": "free" },
  "active_vehicle": "ID.4",
  "server_time": "2026-07-21T12:00:00+00:00"
}

{
  "data": [
    {
      "id": 42, "started_at": "2026-07-20T18:00:00+00:00",
      "ended_at": "2026-07-20T20:30:00+00:00", "energy_kwh": 28,
      "cost_cents": 840, "currency": "EUR", "location_type": "home",
      "charge_type": "ac", "status": "confirmed", "source": "api"
    }
  ]
}

{
  "status": "created",
  "session": { "id": 161, "energy_kwh": 28, "cost_cents": 840, "status": "unconfirmed", "source": "api" }
}

{
  "status": "created",
  "reading": { "id": 12, "reading_km": 42500, "recorded_at": "2026-07-21T10:00:00+00:00" }
}

{
  "ok": true,
  "charging": true,
  "state": { "energy_kwh": 12, "power_kw": 11, "location_type": "home" }
}

curl -X POST https://kilonaut.de/api/v1/sessions \
  -H "Authorization: Bearer <dein-token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-charge-2026-07-20-1800" \
  -d '{
    "started_at": "2026-07-20T18:00:00+02:00",
    "ended_at":   "2026-07-20T20:30:00+02:00",
    "energy_kwh": 28.0,
    "location_type": "home",
    "charge_type": "ac"
  }'

Idempotenz & Rate-Limit

Sende bei POST /sessions einen Header „Idempotency-Key" (oder ein externes „external_id"), damit ein Retry dieselbe Ladung zusammenführt statt zu duplizieren. Das Limit liegt großzügig bei 60 Requests pro Minute je Token.