Log a check-in

What your assistant is told

THE daily check-in tool. When the user describes how their day went in natural language ("I ran, meditated, skipped journaling, had one coffee"), map EACH habit they mention to a check-in and submit them all together in ONE call — this tool is batched on purpose. Per item: - habit_id (required) — from list_habits. - amount — optional, defaults to 1. A habit with a unit REQUIRES the amount in that unit (e.g. 6 glasses). For a CEILING habit (one with a target_max, including abstinence at max 0), log a check-in ONLY when the user reports a slip — saying nothing means they stayed within the limit, so do NOT log anything. - date — the user's LOCAL date (YYYY-MM-DD); omit to use today in tz. Pass the user's IANA tz when you know where they are right now (they may be travelling); omitting it is safe — the server then buckets the day in the time zone on their profile, which is what they told onboarding their streaks run on. - at_iso — optional, the exact moment it happened, ISO-8601 WITH the user's UTC offset (e.g. 2026-06-17T23:30:00+03:00). Omit it and the check-in is stamped now. An offsetless timestamp is REFUSED rather than guessed: the server would have to assume a zone, and a late-night check-in read as UTC lands on the NEXT day — wrong target, wrong heatmap cell, broken streak. If you don't know their offset, ask for it or send date instead. date wins over at_iso for which day the check-in counts toward. Entries that do not clear the habit's entry_filter_min are RECORDED but do NOT count toward the target or the streak. If the user logs a 12-minute practice against a habit whose filter is 20 minutes, say so — "logged, but it's under your 20-minute minimum so it doesn't count as a session" — rather than reporting it as done. Check entry_filter_min from list_habits before confirming. Entries logged inside a habit's gap_minutes are also RECORDED but do NOT count. The result marks such an item too_soon: true with next_allowed_at (UTC — say it in the user's local time): "logged, but it's within 8 hours of the last one, so it doesn't count; the next one can from 21:00". Never present a too-soon entry as done. After logging, confirm back to the user exactly what you recorded (which habits, amounts, and the day). Pass a stable idempotency_key so re-sending the same reflection doesn't double-log. If the result comes back EMPTY, that key was used before and the user has since UNDONE those check-ins — the undo stands and nothing was re-created. Do not retry the same key; log again with a NEW one only if they actually want it back.