A journal your agent can use.

Read and log baby activities through a versioned REST API or a dependency-free Node.js CLI. JSON input, JSON output, explicit timestamps, and retry keys make routine care tasks predictable.

OpenAPI 3.1 specification · Product facts · Download CLI

1. Authorize access

Create an account and set up or join your family in the web app first. The CLI uses the same Supabase authentication as the app. It stores a refreshable session on your computer with owner-only file permissions.

Sessions have the signed-in caregiver’s account permissions. They are not restricted to a read-only scope or a single activity type. Only authorize agents you trust. No administrator or service-role key is needed.

Requires Node.js 22 or newer. Download the CLI above, then sign in without putting your password in a command argument:

read -r -s TATAYA_PASSWORD
printf '%s' "$TATAYA_PASSWORD" | node tataya.mjs login \
  --email YOUR_EMAIL --password-stdin
unset TATAYA_PASSWORD
node tataya.mjs whoami

The read command above is for Bash; in Zsh use read -r -s 'TATAYA_PASSWORD?Password: '. You can also supply a password from your own secret manager through stdin.

For an existing agent runtime, set TATAYA_TOKEN to a current access token from the app’s Settings → Agents & API screen. This short-lived token expires and cannot refresh itself. Use CLI login for a refreshable local session. Do not paste credentials into chat or source files.

2. Read the journal

node tataya.mjs events list \
  --since 2026-11-11T00:00:00+08:00 \
  --until 2026-11-12T00:00:00+08:00 \
  --limit 50

The API returns newest first. If next_cursor is present, pass it as --cursor with the same since and until bounds. Repeat until it is null. The default window is the last seven days; page size is 1–100.

curl 'https://app.tataya.co/api/v1/events?limit=10' \
  -H "Authorization: Bearer $TATAYA_TOKEN"

3. Log an activity

All timestamps must include Z or an explicit UTC offset. Use a stable retry key for each intended event. Retries with the same key and payload return the existing entry. A conflicting payload returns HTTP 409. Keys are scoped to the caregiver, family, and storage category (sleep, feeding, or diaper).

printf '%s' '{"kind":"milk","at":"2026-11-11T12:30:00+08:00","amount_ml":120}' \
  | node tataya.mjs events log --stdin --key feed-20261111-1230

Other event payloads:

{"kind":"sleep","at":"2026-11-11T13:18:00+08:00","sleep_type":"nap"}
{"kind":"solids","at":"2026-11-11T12:00:00+08:00","foods":["Avocado"],"notes":"A few spoonfuls"}
{"kind":"diaper","at":"2026-11-11T11:40:00+08:00","diaper_type":"dirty"}

Sleep entries may include end_at to log a completed session. sleep_type is nap or night. Milk requires amount_ml (1–2000). Solids require 1–30 food names. diaper_type is wet, dirty, or both. Notes are optional on feeds and diapers, up to 2000 characters.

4. End a sleep session

node tataya.mjs sleep end \
  --id YOUR_SLEEP_ENTRY_UUID \
  --at 2026-11-11T14:03:00+08:00

Ending an already-ended session at a different time returns 409. A concurrent update is also rejected so an agent cannot silently overwrite another caregiver’s change.

API reference

Except configuration and login, endpoints require Authorization: Bearer <access_token>. Bodies use Content-Type: application/json. All activity queries are family-scoped and use the caregiver’s Supabase permissions.

Responses and failures

{"data":[{"id":"…","kind":"milk","at":"2026-11-11T04:30:00.000Z","amount_ml":120,"notes":""}],"next_cursor":null,"since":"…","until":"…"}

{"error":{"code":"unauthorized","message":"Send Authorization: Bearer <access_token>","request_id":"…"}}

Successful reads return 200; creates return 201 (200 on replay). Invalid input returns 400, missing or expired credentials 401, denied family access 403, missing records 404, conflicts 409, oversized input 413, and a wrong content type 415. Rate limits return 429 with Retry-After: 60. Transient data service failures return 502 or 503. CLI errors go to stderr as JSON with a nonzero exit code.

Limits: 120 API requests per minute and 10 authentication requests per minute per connection IP on each server instance. JSON bodies are limited to 16 KiB. Production deployments with multiple instances need a shared rate limiter at their reverse proxy.

Local use and credentials

Set TATAYA_URL=http://localhost:8080 to use a local server. The CLI accepts HTTP only on loopback hosts; remote servers require HTTPS. Credentials are stored separately per server origin in ~/.config/tataya/ (or $XDG_CONFIG_HOME/tataya/).

node tataya.mjs logout removes the saved local session. It does not immediately invalidate already-issued tokens. Access tokens remain usable until expiry; manage account sessions through your authentication administrator when revocation is required.

Agent instructions

Read before writing. Confirm the activity, time, and timezone from the caregiver’s request. Never infer an event occurred merely because a sleep suggestion indicated a possible time. Use a unique stable retry key for each event and reuse it after network failures. Keep credentials out of prompts and logs. Sleep suggestions are planning aids, not medical advice.