Cómo se entra
Desde el navegador, con la cookie de sesión que deja el enlace del correo. Desde fuera, con una llave por casa en la cabecera Authorization: Bearer.
La casa la dice siempre la sesión o la llave, nunca la petición: no hay ningún identificador de casa en ninguna URL, porque un número en una URL es un número que alguien va a cambiar por el del vecino.
Lo que se puede leer
GET /api/v1/me da la cuenta y sus bebés. GET /api/v1/babies/<id>/state devuelve la pantalla de hoy entera en una sola respuesta: la predicción, el plan del día y las notas.
GET .../forecast?days=7 da los días que no han llegado con su margen; .../feeds las tomas con sus medias; .../food el plan de la alimentación complementaria. Y GET /api/v1/config publica las constantes del modelo, que es lo que hace que la documentación no pueda desfasarse.
Lo que se puede escribir
POST .../toggle es el botón. POST, PATCH y DELETE sobre .../sleeps corrigen o añaden un sueño; .../feeds/start, /switch y /stop llevan el crono de las tomas.
Las reglas viven en el servidor: solo un sueño abierto a la vez, el final después del principio, y las esperas por edad de la comida se rechazan con el motivo y no con un «no».
Y los errores son claves, no frases
Un error llega como {"error": "sleep.end.before_start"}. El servidor dice qué ha pasado y el cliente lo dice en el idioma que hable.
Es la misma razón por la que las notas del modelo viajan como clave y huecos en vez de como texto: un segundo idioma es un fichero más, no una segunda versión del servidor.