Reminders

A Reminder is an owner-managed definition that creates actionable Notifications without appearing in the Automations collection.
Anchor supports one-time Reminders and annually recurring birthday Reminders.

Use POST /v1/reminders with an idempotency_key, kind, and name.
One-time Reminders also require a future RFC 3339 due_at; their message defaults to the name, and omitted delivery controls use the owner’s backend defaults.
Birthday Reminders require a structured birthday with month, day, and an optional year.
February 29 birthdays occur on February 28 in non-leap years.

Use GET /v1/reminders, GET /v1/reminders/{reminder_id}, PATCH /v1/reminders/{reminder_id}, and DELETE /v1/reminders/{reminder_id} to manage definitions.
Deletion stops future scheduling and cancels outstanding work while preserving Notification history.
An identical create replay returns the existing Reminder with 200; changed content with the same key returns 409.
Replaying a deleted Reminder’s key returns 409 reminder_deleted.

Shared birthday policy

GET /v1/birthday-policy returns the account-wide birthday alert schedule.
Before configuration, the default is one Routine alert at 10:00 on the birthday.
PATCH /v1/birthday-policy replaces or updates the schedule for occasions that have not started.
An occasion that already created its Notification keeps its immutable resolved schedule.

Each step contains a day_offset from -30 through 0, a local HH:MM time, and routine, important, or emergency urgency.
Steps run in chronological order and urgency cannot decrease.
Escalation to Emergency requires explicit opt-in and a Routine sequence must pass through Important before Emergency.

Birthday times use the owner’s home timezone and Anchor’s established daylight-saving-time rules.
Routine and Important steps obey quiet hours, while Emergency steps use the existing bypass.
Global pause follows Automation behavior: Routine and Important birthday occurrences due during the pause are suppressed, Emergency occurrences bypass it, and resuming does not resurrect suppressed work.
Explicit Snooze replays the current urgency without consuming another configured step.
Completing, skipping, or canceling the current Notification stops the remaining alerts for that birthday year but leaves next year’s occasion scheduled.

After downtime, an overdue one-time Reminder is delivered when Anchor recovers unless its explicit deadline has passed.
Birthday recovery sends at most one elapsed step and retains later configured steps through the end of the birthday locally.
Automatic birthday delivery expires at the next local midnight, while an unfinished occurrence remains actionable.

Session callers require CSRF protection for mutations.
API keys use anchor:read for reads and anchor:manage for writes; notifications:create alone cannot manage Reminders.