API de suivi bébé : note tout depuis ton propre code

Le biberon est tiède et le bébé s'est enfin calé sur ton épaule. Le téléphone avec l'appli de suivi, évidemment, charge dans l'autre pièce. Pendant ce temps, un Raspberry Pi ronronne dans le placard du couloir, et une partie têtue de ton cerveau pense déjà : je pourrais juste envoyer une requête POST.

Tu peux. nappi a une API REST publique que toute famille abonnée à nappi Premium peut utiliser avec ses propres données. Tu crées une clé personnelle, tu l'envoies avec chaque requête, et tes scripts peuvent noter les couches, les biberons, l'allaitement, le tire-lait, le sommeil, les activités et la croissance, lancer et arrêter des minuteurs, et lire les dernières entrées. La spécification complète est publique à l'adresse https://api.nappi.app/v1/openapi.json.

nappi a-t-il une API ?

Oui. L'URL de base est https://api.nappi.app/v1, et chaque appel passe en HTTPS classique, avec du JSON à l'aller comme au retour.

L'API est décrite par un document OpenAPI 3.1, le format standard et indépendant du langage pour décrire les API HTTP.¹ Donne la spécification à un générateur de code ou à Postman et tu obtiens un client qui marche, sans deviner le nom des champs.

Si tu préfères cliquer plutôt que lire du JSON, la référence interactive de l'API présente chaque point d'accès (endpoint) avec des exemples. Pas besoin de compte pour la lire. Te connecter sert seulement à afficher tes clés dans le panneau d'essai, pour envoyer de vraies requêtes depuis la page.

L'API est encore en bêta, donc le format des requêtes peut évoluer à mesure qu'on voit comment les familles s'en servent. La référence est générée à partir de l'API en production, elle correspond donc toujours à ce qui est en ligne.

Comment obtenir une clé pour l'API de nappi ?

Les clés se créent sur le web, pas dans l'appli :

1. Connecte-toi sur nappi.app/app/connections, de préférence sur un ordinateur.
2. Donne à la clé un nom que tu reconnaîtras (« Pi de la chambre », « écran de la cuisine ») et choisis sa durée : 30 jours, 90 jours ou 1 an.
3. Copie-la. Elle commence par nappi_, et tu ne la verras qu'une seule fois.

Chaque requête l'envoie dans l'en-tête Authorization sous la forme Bearer nappi_YOUR_KEY, le format de jeton porteur (bearer token) défini par la RFC 6750.² Quiconque détient un jeton porteur peut s'en servir, alors traite le tien comme un mot de passe.

Quelques règles avant de construire quoi que ce soit :

• L'API fait partie de nappi Premium. Un abonnement couvre tout le foyer, et les clés cessent de fonctionner tant que la famille n'a pas Premium.
• Seules les personnes qui s'occupent du bébé peuvent créer des clés. Les observateurs et les invités, non.
• Tu peux avoir jusqu'à 10 clés en même temps.
• On t'envoie un e-mail une semaine avant l'expiration d'une clé que tu utilises.

Que peut faire l'API de nappi ?

Huit points d'accès, tous limités aux bébés de ton foyer :

Méthode	Chemin	Ce qu'il fait
GET	/v1/babies	Liste tes bébés et leurs identifiants
GET	/v1/babies/{babyId}/entries/latest	La dernière entrée de chaque type
GET	/v1/babies/{babyId}/entries/latest/{type}	La dernière entrée d'un type
POST	/v1/babies/{babyId}/entries	Enregistre une entrée terminée
GET	/v1/babies/{babyId}/timers	Les minuteurs de sommeil, d'allaitement et de tire-lait en cours
GET	/v1/babies/{babyId}/status	Minuteurs et dernières entrées en une seule lecture
POST	/v1/babies/{babyId}/timers/{timerType}/start	Lance un minuteur
POST	/v1/babies/{babyId}/timers/{timerType}/stop	Arrête un minuteur et enregistre l'entrée

Ce qui manque compte aussi. Tu ne peux pas encore noter les médicaments ni les solides, même si tu peux lire la dernière entrée de chacun. Et l'API ne renvoie que l'entrée la plus récente de chaque type, pas tout ton historique, sans moyen de modifier ou de supprimer une entrée.

Ta première entrée avec curl

Commence par trouver l'identifiant de ton bébé :

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

Tu reçois un tableau :

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

Ensuite, note une couche mouillée :

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

Un 201 veut dire que c'est noté, et le corps de la réponse indique ce qui a été créé :

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

L'en-tête Idempotency-Key est facultatif. Nous, on ne l'enlèverait jamais d'une automatisation. Si une coupure de connexion pousse ton script à réessayer avec la même clé, la deuxième requête renvoie 200 avec "duplicate": true et rien de nouveau n'est écrit, donc tu ne te retrouves pas avec deux couches.

Une entrée créée par l'API est une entrée nappi comme les autres. Tout le foyer la voit dans l'appli, et elle t'est attribuée, à toi qui as créé la clé.

Les heures sont au format ISO 8601 avec le décalage par rapport à UTC, comme 2026-10-21T14:30:00-04:00, et valent l'heure actuelle par défaut. Les quantités sont en millilitres, sauf si tu envoies "unit": "oz".

Quels types d'entrées peux-tu enregistrer ?

POST /entries prend un type et les champs dont ce type a besoin :

type	Obligatoire	Facultatif
diaper	diaper_type : wet, poo, mixed ou dry	time
potty	outcome : potty, accident ou sat_dry	time
bottle	rien d'autre	amount, unit (ml ou oz), bottle_type (par exemple breast_milk ou formula), time
nursing	rien d'autre	side, left_minutes, right_minutes, duration_minutes, time
pumping	rien d'autre	amount, left_amount, right_amount, unit, duration_minutes, time
sleep	start_time, end_time	sleep_type (nap ou night)
activity	activity_type (par exemple bath ou tummy_time)	duration_minutes, time
growth	rien d'autre	weight, weight_unit (kg ou lb), length, head, length_unit (cm ou in), time

Un biberon de 4 onces de lait infantile ressemble à ça :

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

Sans sleep_type, nappi choisit entre sieste et nuit d'après les horaires de journée du bébé, comme le fait l'appli. Pour quelque chose qui est encore en cours, comme une sieste qui vient de commencer, utilise un minuteur.

Lancer et arrêter un minuteur de sommeil depuis un script

Les minuteurs sont les mêmes, partagés, que tout le foyer voit dans l'appli. Pour lancer une sieste :

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

L'arrêter enregistre l'entrée de sommeil, exactement comme si tu l'arrêtais sur le téléphone :

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

timerType peut valoir sleep, nursing ou pumping. Lancer un minuteur déjà en marche ne change rien et le renvoie avec "status": "already_running". L'arrêter alors que rien ne tourne renvoie 409 avec le code timer_not_running, ce qui permet de faire facilement un seul bouton marche/arrêt.

Ça marche dans les deux sens. GET /timers renvoie aussi les minuteurs lancés par quelqu'un sur un téléphone, une montre ou avec Alexa. Ceux d'allaitement acceptent un side facultatif, et start_time permet d'antidater le début de 48 heures au maximum.

Un petit script : le temps écoulé depuis la dernière tétée

Ce script Node (Node 18 ou plus récent, sans paquet) affiche depuis combien de temps le bébé a mangé, biberons et allaitement compris. Enregistre-le sous last-feed.mjs et lance 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`);
}

Branche-le sur une tâche cron et un écran à encre électronique sur le frigo, et plus personne n'a besoin de déverrouiller son téléphone à 3 h du matin pour savoir quand date le dernier biberon.

Interroger l'API sans dépasser la limite

Chaque clé a droit à 12 lectures et 30 écritures par minute. Au-delà, tu reçois 429 Too Many Requests, avec un en-tête Retry-After qui indique combien de secondes attendre.³⁴

Pour un tableau de bord, interroge /status au plus une fois par minute. Ses réponses portent un ETag. Renvoie-le dans If-None-Match et tu reçois 304 Not Modified, sans corps, tant que rien ne change.⁴

Il y a une exception. Quand un minuteur tourne, son temps écoulé change chaque seconde, donc /status renvoie toujours un 200 complet.

Raccourcis sur iPhone : un biberon en un geste

Pas besoin d'ordinateur pour celui-ci. Dans l'app Raccourcis, ajoute l'action Obtenir le contenu de l'URL et règle-la ainsi :

• URL : https://api.nappi.app/v1/babies/BABY_ID/entries
• Méthode : POST
• En-têtes : Authorization avec la valeur Bearer nappi_YOUR_KEY
• Demander le corps : JSON, avec type sur bottle, amount sur 120 (en tant que Nombre) et unit sur ml

C'est en passant la méthode sur POST qu'apparaît le champ « Demander le corps », et JSON fait partie de ses options.⁵ Ajoute le raccourci à ton écran d'accueil, ou place avant une étape « Demander une entrée » pour taper la quantité à chaque fois.

L'appli nappi gère déjà la saisie vocale avec Siri. Cette méthode sert pour le sur-mesure, comme un bouton « 120 ml de lait infantile » en un geste ou une automatisation qui se déclenche quand le téléphone touche une étiquette NFC collée sur l'égouttoir à biberons.

Home Assistant : l'intégration ou de simples commandes REST

Si Home Assistant pilote ta maison, commence par l'intégration. Elle est open source sous licence MIT (nappi-app/nappi-home-assistant sur GitHub), et tu la trouves dans les dépôts par défaut de HACS en cherchant « nappi ». Elle interroge /status une fois toutes les 2 minutes par bébé et te donne des boutons de saisie, des interrupteurs de minuteur et des capteurs de dernière entrée sans toucher au YAML. Notre guide Home Assistant détaille l'installation pas à pas, avec quelques automatisations à recopier.

Tu préfères le YAML ? L'intégration RESTful Command de Home Assistant peut appeler l'API directement, avec tes propres en-têtes et un corps JSON.⁶ Ces deux commandes lancent et arrêtent une sieste :

# 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

Appelle rest_command.nappi_sleep_start depuis un bouton près du berceau, et le minuteur de sieste démarre sur les téléphones de toute la famille. La page maison connectée liste les autres façons de connecter nappi, dont Alexa et Google Home.

Est-ce sûr de donner à un script l'accès aux données de mon bébé ?

Rien ne peut lire les données de ta famille via l'API tant que tu n'as pas créé de clé. Chaque clé appartient à une personne qui s'occupe du bébé, dans un seul foyer, et nappi n'en garde qu'une empreinte SHA-256. C'est pour ça que tu ne vois la clé qu'une fois.

Tu peux révoquer une clé quand tu veux sur nappi.app/app/connections, ou dans l'appli sous Réglages → Connexions → Maison connectée. Une clé cesse aussi de fonctionner quand elle expire, ou si tu quittes le foyer ou deviens observateur.

Une clé peut noter et lire pour ta famille comme tu le fais dans l'appli, minuteurs compris. Elle ne peut ni modifier ton compte ni voir ton mot de passe. Garde-la hors des dépôts Git publics et des captures d'écran, et révoque-la dès qu'elle fuite.

Essaie ce soir : crée une clé de 30 jours, lance le curl sur /babies et note une couche de test. Quand elle apparaît sur le téléphone de ton ou ta partenaire, supprime-la depuis l'appli, puisque l'API ne peut pas le faire.

Questions fréquentes

L'API de nappi coûte-t-elle plus cher ?

Il n'y a pas de supplément, mais l'API fait partie de nappi Premium. Un abonnement couvre tout ton foyer. Lire la documentation et la spécification OpenAPI est gratuit pour tout le monde.

Puis-je exporter tout mon historique via l'API ?

Non. L'API renvoie la dernière entrée de chaque type et les minuteurs en cours. Pour ton historique complet, utilise l'export CSV de l'appli nappi.

Est-ce que ça marche avec des jumeaux ou une fratrie ?

Oui. GET /v1/babies renvoie tous les bébés de ton foyer, et chaque autre appel désigne un bébé par son identifiant. Lance ton script une fois par bébé.

Puis-je noter les médicaments via l'API ?

Pas encore. Tu peux lire la dernière entrée de médicament, mais noter des médicaments ou des solides n'est pas possible, alors continue d'utiliser l'appli pour ça.