Dates, Progress, and Writes
Understand server-synced data, streak units, retries, and conflicts.
Dates are Gregorian calendar days (YYYY-MM-DD). Supply an IANA time zone, such as America/Los_Angeles, when
reading a day's habits or recording a check-in. Capture the intended day once; do not reinterpret yesterday in UTC.
An existing check-in's recorded time zone is returned with it. Preserve that zone when undoing or correcting it.
The public integration accepts dates from 1900 through 2100. Future check-ins are rejected. History requests cover at most 366 days.
A completion is one habit's checked or unchecked state on one date. A missing record is incomplete. Check-ins and schedules are the source of truth. Streaks are derived and have a unit: days, times, or weeks. Daily, weekday, weekly target, and every-few-days schedules follow the same rules as the app. Breaks pause relevant missed periods. An open today or week does not end a run before that period finishes.
Read before writing
Read the habit and check-in revisions through list_habits. Send both revisions, the desired completed boolean,
and a new UUID requestID to set_completion. A missing check-in has a null revision. The habit revision also
protects against an intervening schedule or sharing change.
A successful response confirms server persistence. If the response is lost, retry the exact same input and request ID to recover the original result. A different input under the same ID conflicts. A stale revision also conflicts: read the current state and reconsider the change before creating a new request. Read-only keys cannot record changes.
Recording a shared habit can publish a check-in and trigger friend notifications under your existing settings. Undo hides that shared check-in. The integration uses the app's existing publication and notification rules.
Offline phones
Reads reflect the server snapshot at asOf. This timestamp does not promise that every device has synchronized.
An online phone learns about a write through a sync notification and pull. A phone with queued offline edits
reconciles when it reconnects; conflicting phone writes follow server application order. Pending offline work is
not visible to the assistant until uploaded. Reminder changes are outside this first API.
Errors
HTTP authentication failures return 401, insufficient access returns 403, unavailable habits return 404, and revision
or request conflicts return 409. Invalid arguments return 400. A rate-limited connection returns 429 and Retry-After.
Errors include a stable code, a readable message, a diagnostic request ID, and whether retrying can help. Authentication
failures require reconnection; conflicts require a fresh read. Retry temporary failures with bounded backoff and the
same write request ID. MCP tool failures return isError; transport authentication failures remain HTTP errors.
Connect Muse to Sundial Habits
Let Muse read your habits and streaks, or check off a habit for you. Follow this short setup guide.
Get Check-in History GET
Read one habit’s recorded check-ins over up to 366 calendar days, including explicit undo records. Missing dates are incomplete. Results reflect server-synced data.