Cradlewise Data API → Home Assistant

A small MQTT bridge that integrates the official Cradlewise Data API (launched July 2026, beta) into Home Assistant — written the day the API launched, as a real-world integration exercise.

It polls the API and publishes entities via MQTT discovery, so Home Assistant picks everything up automatically with zero YAML.

Looking for live video? The official Data API is data-only. See WEBRTC-VIDEO.md for how we bridged the crib's WebRTC feed into RTSP for Home Assistant and UniFi Protect — and why an official video endpoint would make all of it unnecessary.

What it does

Entity	Source	Update cadence
Baby status (sleeping/awake/stirring/crying/away)	/baby/status	40 s
In crib (occupancy binary sensor)	/baby/status	40 s
Bounce mode / Music mode	/baby/status	40 s
Soothes / naps today	/sleep/day-metrics	15 min
Time in bed / awake in bed / longest stretch today	/sleep/day-metrics	15 min
Rise time / bedtime today (timestamps)	/sleep/day-metrics	15 min
Total / day / night sleep today	/sleep/c-chart day aggregates	15 min
Last session summary (+ start/end/sleep attributes)	/sleep/c-chart sessions	15 min

Cadences respect the documented rate limits (status: 2/min, sleep endpoints: 60/hr, global: 2,880/day) with headroom, honor Retry-After on 429, and warn when X-RateLimit-Remaining runs low.

Sleep "days" are handled on the Cradlewise day boundary (default 8:00 AM local), not midnight, matching the app.

Running it

docker build -t cradlewise-api-poller .
docker run -d \
  -e CRADLEWISE_API_TOKEN=cw_your_token_here \
  -e MQTT_HOST=your-mqtt-broker \
  -e BABY_NAME=YourBabyName \
  -e TZ=America/Los_Angeles \
  cradlewise-api-poller

Requires an MQTT broker that Home Assistant's MQTT integration is connected to. Entities appear under one device (Cradlewise <name> API).

Token: created by the account admin at integrations.cradlewise.com (requires Nurture Plus).

Notes for the Cradlewise API team

First: thank you for shipping an official API — this replaced a pile of reverse-engineered Cognito/MQTT auth that broke every few months. Some observations from building against it on launch day, and a wishlist:

Observations

1. Timestamp consistency. /baby/status returns ISO-8601 UTC with Z (great). day-metrics/c-chart return naive timestamps (2026-07-17 15:18:24.489658) that are actually UTC, while date / day_start_time fields in the same responses are local time. A consistent format (ideally ISO-8601 with offset everywhere) would remove guesswork.
2. Partial days work well — hitting day-metrics mid-day returns nulls for not-yet-known metrics (bedtime, time in bed). Documenting that behavior would help.
3. display_value + raw value pairing is genuinely useful — keep that pattern.

Wishlist (roughly in priority order)

1. Live video access. The #1 integration ask for a baby monitor: an official way to get the camera stream (RTSP/RTSPS, WebRTC signaling, or even HLS) so the crib can appear in Home Assistant and NVRs (UniFi Protect, Frigate, Scrypted) without reverse-engineering the app's Janus/WebRTC flow. Read-only, LAN-local would be ideal. Even a documented, supported version of the current cloud WebRTC room-join flow would be a huge step.
2. Push instead of poll for status. A webhook, SSE stream, or MQTT feed for baby-status transitions (sleeping → crying etc.). The 2/min polling limit means up to 30 s latency on a cry notification, which is the one place latency matters.
3. Token lifecycle. 60-day tokens with no programmatic refresh means every integration dies silently every two months. A refresh endpoint, longer-lived tokens, or at least an expiry timestamp on a /token/info endpoint (so integrations can warn before expiry) would help a lot.
4. Documented enums. The full set of status values and crib_mode values (bounce/music states), so integrations can map them to proper state machines without discovering values empirically.
5. Historical backfill bounds. Documented max look-back window for the sleep endpoints, for stats/recorder-style integrations.
6. Multi-baby tokens or an account-level token with a /babies index, for households with more than one crib.
7. Control endpoints (longer term): start/stop soothing, music, night light — even behind an explicit opt-in scope. This would enable "good night" scenes and automations.

Architecture note

This runs in a Docker Swarm homelab alongside a separate (unofficial) WebRTC → RTSP bridge for the video feed. The Data API covers everything except video; wishlist item #1 would let us delete the most fragile code in the stack.

License

MIT