Baby-Tracker-API: Schlaf und Mahlzeiten per Code erfassen

Das Fläschchen ist warm, und das Baby hat sich endlich auf deiner Schulter eingekuschelt. Das Handy mit der Baby-App lädt natürlich gerade im anderen Zimmer. Währenddessen summt im Flurschrank ein Raspberry Pi, und ein sturer Teil deines Gehirns denkt schon: Ich könnte doch einfach einen POST-Request schicken.

Kannst du auch. nappi hat eine öffentliche REST-API, die jede Familie mit nappi Premium für ihre eigenen Daten nutzen kann. Du erstellst einen persönlichen Schlüssel, schickst ihn bei jeder Anfrage mit, und deine Skripte können Windeln, Fläschchen, Stillen, Abpumpen, Schlaf, Aktivitäten und Wachstum erfassen, Timer starten und stoppen und die neuesten Einträge lesen. Die vollständige Spezifikation ist öffentlich unter https://api.nappi.app/v1/openapi.json.

Hat nappi eine API?

Ja. Die Basis-URL ist https://api.nappi.app/v1, und jeder Aufruf ist ganz normales HTTPS, mit JSON hin und zurück.

Beschrieben ist die API in einem OpenAPI-3.1-Dokument, dem standardisierten, sprachunabhängigen Format für HTTP-APIs.¹ Gib die Spezifikation einem Codegenerator oder Postman, und du bekommst einen funktionierenden Client, ohne Feldnamen raten zu müssen.

Wenn du lieber klickst, als JSON zu lesen, zeigt die interaktive API-Referenz jeden Endpunkt mit Beispielen. Zum Lesen brauchst du kein Konto. Wenn du dich anmeldest, listet das Testfeld nur deine Schlüssel auf, damit du direkt von der Seite echte Anfragen schicken kannst.

Die API ist noch als Beta gekennzeichnet, das Format der Anfragen kann sich also ändern, während wir sehen, wie Familien sie nutzen. Die Referenz wird aus der laufenden API erzeugt und passt deshalb immer zu dem, was gerade live ist.

Wie bekomme ich einen Schlüssel für die nappi-API?

Schlüssel erstellst du im Web, nicht in der App:

1. Melde dich unter nappi.app/app/connections an, am besten am Computer.
2. Gib dem Schlüssel einen Namen, den du später wiedererkennst („Pi im Kinderzimmer“, „Küchen-Dashboard“), und wähle, wie lange er gilt: 30 Tage, 90 Tage oder 1 Jahr.
3. Kopiere ihn. Er beginnt mit nappi_, und du siehst ihn nur ein einziges Mal.

Jede Anfrage schickt ihn im Header Authorization als Bearer nappi_YOUR_KEY, im Bearer-Token-Format aus RFC 6750.² Wer ein Bearer-Token hat, kann es benutzen. Behandle deins also wie ein Passwort.

Ein paar Regeln, bevor du loslegst:

• Die API ist Teil von nappi Premium. Ein Abo gilt für den ganzen Haushalt, und Schlüssel funktionieren nicht, solange die Familie kein Premium hat.
• Nur Betreuungspersonen können Schlüssel erstellen. Beobachter und Gäste nicht.
• Du kannst bis zu 10 Schlüssel gleichzeitig haben.
• Eine Woche bevor ein Schlüssel abläuft, den du benutzt, bekommst du eine E-Mail von uns.

Was kann die nappi-API?

Acht Endpunkte, alle auf die Babys in deinem Haushalt beschränkt:

Methode	Pfad	Was er macht
GET	/v1/babies	Listet deine Babys und ihre IDs auf
GET	/v1/babies/{babyId}/entries/latest	Neuester Eintrag jeder Art
GET	/v1/babies/{babyId}/entries/latest/{type}	Neuester Eintrag einer Art
POST	/v1/babies/{babyId}/entries	Speichert einen abgeschlossenen Eintrag
GET	/v1/babies/{babyId}/timers	Laufende Timer für Schlaf, Stillen und Abpumpen
GET	/v1/babies/{babyId}/status	Timer und neueste Einträge in einem Abruf
POST	/v1/babies/{babyId}/timers/{timerType}/start	Startet einen Timer
POST	/v1/babies/{babyId}/timers/{timerType}/stop	Stoppt einen Timer und speichert den Eintrag

Was fehlt, ist auch wichtig. Medikamente und Beikost kannst du noch nicht erfassen, den jeweils neuesten Eintrag aber lesen. Außerdem liefert die API pro Art nur den neuesten Eintrag, nicht deinen ganzen Verlauf, und Einträge lassen sich darüber weder bearbeiten noch löschen.

Dein erster Eintrag mit curl

Finde zuerst die ID deines Babys heraus:

curl https://api.nappi.app/v1/babies \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Zurück kommt ein Array:

[
  {
    "id": "BABY_ID",
    "name": "Phoebe",
    "birth_date": "2026-05-02",
    "timezone": "America/New_York"
  }
]

Dann erfasst du eine nasse Windel:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/entries \
  -H "Authorization: Bearer nappi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "diaper", "diaper_type": "wet"}'

Ein 201 heißt, der Eintrag ist gespeichert, und der Body sagt dir, was angelegt wurde:

{ "id": "ENTRY_ID", "type": "diaper", "duplicate": false }

Der Header Idempotency-Key ist optional. Wir würden ihn trotzdem in keiner Automatisierung weglassen. Wenn die Verbindung abbricht und dein Skript es mit demselben Schlüssel erneut versucht, liefert die zweite Anfrage 200 mit "duplicate": true, und es wird nichts Neues geschrieben. Du landest also nicht bei zwei Windeln.

Ein Eintrag über die API ist ein ganz normaler nappi-Eintrag. Alle im Haushalt sehen ihn in der App, und er wird dir zugeordnet, also der Person, die den Schlüssel erstellt hat.

Zeiten sind im Format ISO 8601 mit UTC-Versatz, etwa 2026-10-21T14:30:00-04:00, und standardmäßig gilt die aktuelle Zeit. Mengen sind in Millilitern, es sei denn, du schickst "unit": "oz" mit.

Welche Eintragsarten kannst du speichern?

POST /entries nimmt einen type und die Felder, die diese Art braucht:

type	Pflicht	Optional
diaper	diaper_type: wet, poo, mixed oder dry	time
potty	outcome: potty, accident oder sat_dry	time
bottle	sonst nichts	amount, unit (ml oder oz), bottle_type (zum Beispiel breast_milk oder formula), time
nursing	sonst nichts	side, left_minutes, right_minutes, duration_minutes, time
pumping	sonst nichts	amount, left_amount, right_amount, unit, duration_minutes, time
sleep	start_time, end_time	sleep_type (nap oder night)
activity	activity_type (zum Beispiel bath oder tummy_time)	duration_minutes, time
growth	sonst nichts	weight, weight_unit (kg oder lb), length, head, length_unit (cm oder in), time

Ein Fläschchen mit 4 Unzen Säuglingsnahrung sieht so aus:

{ "type": "bottle", "amount": 4, "unit": "oz", "bottle_type": "formula" }

Lässt du sleep_type weg, entscheidet nappi anhand der Tageszeiten des Babys zwischen Nickerchen und Nacht, genau wie die App. Für etwas, das noch läuft, etwa ein angefangenes Nickerchen, nimmst du einen Timer.

Schlaf-Timer per Skript starten und stoppen

Die Timer sind dieselben gemeinsamen Timer, die der ganze Haushalt in der App sieht. So startest du ein Nickerchen:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Beim Stoppen wird der Schlafeintrag gespeichert, genau so, als würdest du ihn am Handy stoppen:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop \
  -H "Authorization: Bearer nappi_YOUR_KEY"

timerType kann sleep, nursing oder pumping sein. Einen Timer zu starten, der schon läuft, ändert nichts und liefert ihn mit "status": "already_running" zurück. Stoppen, obwohl nichts läuft, liefert 409 mit dem Code timer_not_running. Damit ist ein einzelner Ein/Aus-Knopf schnell gebaut.

Das funktioniert in beide Richtungen. GET /timers liefert auch Timer, die jemand am Handy, an der Uhr oder mit Alexa gestartet hat. Still-Timer nehmen optional eine side, und mit start_time kannst du den Start um bis zu 48 Stunden zurückdatieren.

Ein kleines Skript: Zeit seit der letzten Mahlzeit

Dieses Node-Skript (Node 18 oder neuer, ohne Pakete) zeigt an, wie lange die letzte Mahlzeit her ist, Fläschchen und Stillen zusammengerechnet. Speichere es als last-feed.mjs und starte es mit node last-feed.mjs:

const KEY = "nappi_YOUR_KEY";
const BABY = "BABY_ID";

const res = await fetch(
  `https://api.nappi.app/v1/babies/${BABY}/status?types=bottle,nursing`,
  { headers: { Authorization: `Bearer ${KEY}` } },
);
if (!res.ok) throw new Error(`nappi returned ${res.status}`);
const { timers, latest } = await res.json();

const feeds = [latest.bottle, latest.nursing].filter(Boolean);
if (timers.some((t) => t.type === "nursing")) {
  console.log("Nursing right now");
} else if (feeds.length === 0) {
  console.log("No feeds logged yet");
} else {
  const last = Math.max(...feeds.map((f) => new Date(f.time).getTime()));
  const min = Math.round((Date.now() - last) / 60000);
  console.log(`Last feed ${Math.floor(min / 60)}h ${min % 60}m ago`);
}

Häng es an einen Cronjob und ein E-Ink-Display am Kühlschrank, und niemand muss um 3 Uhr nachts das Handy entsperren, um herauszufinden, wann das letzte Fläschchen war.

Abfragen, ohne ins Limit zu laufen

Jeder Schlüssel hat 12 Lese- und 30 Schreibzugriffe pro Minute. Gehst du darüber, bekommst du 429 Too Many Requests mit einem Retry-After-Header, der sagt, wie viele Sekunden du warten sollst.³⁴

Für ein Dashboard fragst du /status höchstens einmal pro Minute ab. Die Antworten tragen ein ETag. Schick es als If-None-Match zurück, und du bekommst 304 Not Modified ohne Body, bis sich etwas ändert.⁴

Eine Ausnahme gibt es. Solange ein Timer läuft, ändert sich seine verstrichene Zeit jede Sekunde, deshalb liefert /status dann immer ein vollständiges 200.

Kurzbefehle auf dem iPhone: ein Fläschchen mit einem Tipp

Dafür brauchst du keinen Computer. Füge in der App Kurzbefehle die Aktion Inhalte von URL abrufen hinzu und stell sie so ein:

• URL: https://api.nappi.app/v1/babies/BABY_ID/entries
• Methode: POST
• Header: Authorization mit dem Wert Bearer nappi_YOUR_KEY
• Haupttext anfordern: JSON, mit type auf bottle, amount auf 120 (als Zahl) und unit auf ml

Erst wenn du die Methode auf POST stellst, erscheint das Feld „Haupttext anfordern“, und JSON ist eine seiner Optionen.⁵ Leg den Kurzbefehl auf deinen Home-Bildschirm oder setz davor einen Schritt „Nach Eingabe fragen“, damit du die Menge jedes Mal eintippen kannst.

Sprachbefehle mit Siri kann die nappi-App schon selbst. Dieser Weg ist für Eigenes gedacht, zum Beispiel einen Ein-Tipp-Knopf für „120 ml Säuglingsnahrung“ oder eine Automation, die startet, wenn dein Handy einen NFC-Sticker am Fläschchen-Abtropfgestell berührt.

Home Assistant: die Integration oder einfache REST-Befehle

Wenn Home Assistant dein Zuhause steuert, fang mit der Integration an. Sie ist Open Source unter MIT-Lizenz (nappi-app/nappi-home-assistant auf GitHub), und du findest sie in den Standard-Repositorys von HACS, wenn du nach „nappi“ suchst. Sie fragt /status alle 2 Minuten pro Baby ab und gibt dir Knöpfe zum Erfassen, Timer-Schalter und Sensoren für den letzten Eintrag, ganz ohne YAML. Unsere Anleitung für Home Assistant zeigt die Installation Schritt für Schritt, dazu ein paar Automationen zum Nachbauen.

Lieber YAML? Die Integration RESTful Command von Home Assistant kann die API direkt aufrufen, mit eigenen Headern und JSON-Body.⁶ Diese beiden Befehle starten und stoppen ein Nickerchen:

# secrets.yaml
nappi_auth: "Bearer nappi_YOUR_KEY"

# configuration.yaml
rest_command:
  nappi_sleep_start:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start"
    method: post
    headers:
      Authorization: !secret nappi_auth
  nappi_sleep_stop:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop"
    method: post
    headers:
      Authorization: !secret nappi_auth

Ruf rest_command.nappi_sleep_start über einen Knopf am Bettchen auf, und der Nickerchen-Timer startet auf allen Handys der Familie. Auf der Smart-Home-Seite findest du die anderen Verbindungswege, darunter Alexa und Google Home.

Ist es sicher, einem Skript Zugriff auf die Daten meines Babys zu geben?

Über die API kann niemand die Daten deiner Familie lesen, solange du keinen Schlüssel erstellt hast. Jeder Schlüssel gehört einer Betreuungsperson in einem Haushalt, und nappi speichert davon nur einen SHA-256-Hash. Deshalb siehst du den Schlüssel einmal und danach nie wieder.

Widerrufen kannst du einen Schlüssel jederzeit unter nappi.app/app/connections oder in der App unter Einstellungen → Verbindungen → Smart Home. Ein Schlüssel funktioniert außerdem nicht mehr, wenn er abläuft, wenn du den Haushalt verlässt oder zum Beobachter wirst.

Ein Schlüssel kann für deine Familie erfassen und lesen wie du in der App, Timer eingeschlossen. Dein Konto ändern oder dein Passwort sehen kann er nicht. Halte ihn aus öffentlichen Git-Repos und Screenshots heraus, und widerrufe ihn sofort, falls er irgendwo auftaucht.

Probier es heute Abend aus: Erstell einen Schlüssel für 30 Tage, führ das curl für /babies aus und erfasse eine Test-Windel. Sobald sie auf dem Handy deines Partners oder deiner Partnerin auftaucht, lösch sie dort, denn die API kann das nicht.

Häufig gestellte Fragen

Kostet die nappi-API extra?

Es gibt keine gesonderte Gebühr, aber die API ist Teil von nappi Premium. Ein Abo gilt für alle in deinem Haushalt. Die Dokumentation und die OpenAPI-Spezifikation kann jeder kostenlos lesen.

Kann ich meinen ganzen Verlauf über die API exportieren?

Nein. Die API liefert den neuesten Eintrag jeder Art und die laufenden Timer. Für deinen kompletten Verlauf nutzt du den CSV-Export in der nappi-App.

Funktioniert das mit Zwillingen oder Geschwistern?

Ja. GET /v1/babies liefert alle Babys in deinem Haushalt, und jeder andere Aufruf nennt ein Baby über seine ID. Lass dein Skript einfach einmal pro Baby laufen.

Kann ich Medikamente über die API erfassen?

Noch nicht. Den neuesten Medikamenteneintrag kannst du lesen, aber Medikamente oder Beikost zu erfassen geht noch nicht. Dafür nimmst du weiter die App.