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

Connect ChatGPT or Claude with a sign-in

For a hosted chatbot, use the parent-friendly connection guide. Add https://app.tataya.co/mcp as a remote MCP connector, choose OAuth and automatic client registration, then sign in to tataya. You choose Read only or Read and log. Access refreshes automatically; no token pasting or terminal is needed.

The connector uses Streamable HTTP with stateless JSON responses, OAuth authorization code with PKCE S256, and Supabase Auth. Discovery is at the protected resource metadata endpoint. A connected AI has only its chosen journal permission and cannot change account settings, manage share codes or create credentials.

Tools: get_journal, list_activities, log_activity, end_sleep, edit_sleep and edit_ongoing_sleep. Activity times require an explicit UTC offset. log_activity requires an idempotency key. Edits require the revision read from the current sleep. Disconnect in Settings → Agents & API → Connect your AI; journal access stops immediately, including for an unexpired access token.

Custom connector availability depends on the AI plan or workspace. tataya is not currently listed in either chatbot's directory. Other OAuth-capable remote MCP clients can use this endpoint; consumer Gemini support has not been verified. For Muse, use an agent key below.

1. Authorize API or CLI access

Create an account and set up or join your family in the web app first.

Set up once with an agent key

1. Open Settings → Agents & API → Connect your AI → Use an agent key.
2. Name your agent and choose Read only or Read and log.
3. Choose Create agent key, then Copy agent key. The raw key starts with ttk_ and is shown only during this setup.
4. Save only the raw key in your AI's private credential field, without Bearer, quotes or extra text. Keep it out of chat, source files and logs.
5. Choose “I’ve saved the key in my AI,” then Copy connection message. Paste that message into your AI; it contains no key and asks for a read-only check of /me and /events?limit=1.
6. Check connection in tataya looks for a new authenticated request since setup opened. Copying a key alone does not mean the AI connected. A saved connection can be resumed with Use saved key, without creating another key.

Agent keys have no automatic expiry and do not depend on your browser session. They are limited to one family and the access you selected. Revoke a key from this same Settings dialog to stop its future requests. Leaving the family, losing account access or deleting the account also stops access. tataya stores a hash of the key, not the raw secret. A key cannot create other keys or manage your account.

The CLI accepts an agent key through TATAYA_TOKEN; no password login is needed for that mode. Configure the secret in the agent's persistent settings so it remains available across new conversations and restarted environments. Changing a temporary token into a key requires creating a key and replacing the old credential; a temporary token itself cannot be extended.

Which address and credential?

HTTP clients use https://app.tataya.co/api/v1 and add one Authorization: Bearer prefix around the saved raw key. The official CLI uses TATAYA_URL=https://app.tataya.co (without /api/v1) and TATAYA_TOKEN contains only the raw key. Do not send a tataya agent key to Supabase Auth.

If you see “sign-in token invalid or expired,” the request went through the temporary sign-in-token path. Check the saved credential and API address. An invalid_agent_key response means the supplied key is unknown, revoked or no longer has family access. Give support the HTTP status, error.code and request_id; never send the credential.

Alternative: refreshable CLI sign-in

The CLI can also store a refreshable caregiver session locally with owner-only file permissions. These sign-in sessions use your account permissions and refresh automatically. Temporary access tokens are separate under Settings → Agents & API → Developer tools → Temporary access token. They are for short tests, expire and do not refresh themselves. Use the guided agent-key flow for Muse.

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.

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. Set sleep_type to night for night sleep; API requests default to nap when the field is omitted. The web timer asks you to choose the type explicitly. 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.

5. Correct a sleep entry

Any caregiver in the family with write access can correct a sleep's end time, start time or type, including a sleep that has already ended. Read the entry first. Send the fields you want to change and copy its current at, end_at, sleep_type and revision into expected. The entry keeps its ID and original author; duration is recalculated and edited_by and edited_at record the latest editor. Do not delete and recreate the entry.

For example, if the current night sleep ends at 3:00 AM UTC but the caregiver says it ended at 2:30 AM UTC, save this as sleep-correction.json, replacing the example snapshot with the values you just read:

{
  "end_at": "2026-11-13T02:30:00Z",
  "expected": {
    "at": "2026-11-12T19:00:00.000Z",
    "end_at": "2026-11-13T03:00:00.000Z",
    "sleep_type": "night",
    "revision": 1
  }
}

node tataya.mjs sleep edit --id SLEEP_ID --stdin < sleep-correction.json

Or send the same JSON to PATCH https://app.tataya.co/api/v1/events/sleep/{id} with your usual authorization. With the hosted MCP connector, use edit_sleep; include id alongside these fields.

A stale snapshot returns 409 concurrent_update. Read the entry again before deciding whether to retry; never overwrite another caregiver's later change. Times require Z or an explicit UTC offset. The end must be after the start, and corrected times cannot be in the future. Omitted fields retain their values; end_at: null cannot reopen a completed sleep.

Editing an ongoing sleep

The same edit_sleep tool and CLI command can correct a running sleep's start or type. Copy end_at: null into expected and omit the new end_at to leave its timer running. The existing edit_ongoing_sleep tool remains available. The web app's ongoing-sleep editor offers Undo for 10 seconds; an agent can undo a correction by sending the previous values with a fresh snapshot, only when the caregiver requests it.

API reference

Except configuration and login, endpoints require Authorization: Bearer <agent_key_or_access_token>. Bodies use Content-Type: application/json. All activity queries are family-scoped. Agent keys enforce their configured read/write permission and current family membership; sign-in sessions 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 <agent_key_or_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, including status and request_id when returned by the API. Revoked or no-longer-authorized agent keys return 401 invalid_agent_key; a read-only key attempting a write returns 403 insufficient_scope. Invalid sign-in access tokens return 401 unauthorized; a valid account without family access returns 403 forbidden or family_required. Failed sign-in returns 401 invalid_credentials, and an invalid refresh session returns 401 invalid_refresh_token. Confirming your email may be required before sign-in (403 email_confirmation_required).

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.

HTTP client identification

Send a descriptive User-Agent such as my-caregiver-agent/1.0 when using an HTTP library. Cloudflare Pages can reject library-default signatures such as Python urllib with a plain-text 403 error code: 1010, before the request reaches tataya. This is an edge rejection, not a family-access error. The official CLI sends tataya-cli/1.0. A browser User-Agent is not required.

import json
from urllib.request import Request, urlopen

request = Request(
    "https://app.tataya.co/api/v1/config",
    headers={"User-Agent": "my-caregiver-agent/1.0"},
)
with urlopen(request, timeout=15) as response:
    print(json.load(response))

This public configuration request needs no access token. For journal requests, add your agent key or sign-in token through your client's secure credential storage. See Cloudflare's explanation of error 1010.

Production and local use

The live API base is https://app.tataya.co/api/v1. The CLI uses https://app.tataya.co by default, so you do not need to set TATAYA_URL for the live app. The localhost example below is only for a server running on your own computer.

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. Sign-in access tokens remain usable until expiry. Agent keys are separate: remove them from the agent runtime and revoke them in Settings to stop access. CLI logout does not revoke an agent key.

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. Payload validation runs before Idempotency-Key validation; both complete before an event is written. Keep credentials out of prompts and logs. Sleep suggestions are planning aids, not medical advice.