Times, lengths and reminders

A to-do's whenDate puts it on a day. Three more fields place it within that day:

All three are local wall-clock values with no zone, like reminderTime: a to-do at 09:00 stays at 09:00 when the user travels. All three are end-to-end encrypted.

Setting a time

Send the fields on POST /v1/todos or PATCH /v1/todos/{id}. This puts a dentist appointment at 16:00 for an hour, with a reminder 15 minutes before:

curl -s -X PATCH "https://api.inittasks.com/v1/todos/$TODO" \
  -H "Authorization: Bearer $INITTASKS_TOKEN" -H "Content-Type: application/json" \
  -d '{"whenDate": "2026-10-12", "whenTime": "16:00", "durationMin": 60, "reminders": [{"before": 15}]}'

The to-do comes back with the three fields as the apps read them:

{ "whenDate": "2026-10-12", "whenTime": "16:00", "durationMin": 60,
  "reminders": [{ "before": 15 }], "reminderTime": "2026-10-12T15:45", "…": "…" }

A start on a to-do with no date dates it today, as the apps do. Send ?today=yyyy-MM-dd with the user's local date so "today" is their day, not the server's UTC day. A start together with "whenDate": null is refused.

Reminders

A reminder is one of two kinds:

• { "before": 15 } counts back from the start: 0 is at the start, 60 an hour before, 1440 a day before, 10080 a week before. It needs a whenTime.
• { "at": "2026-10-11T20:00" } is a fixed moment that stays put.

reminders replaces the whole list. A to-do holds at most 5, kept in the order they ring. Two reminders that ring at the same moment, a before with no start, or a sixth reminder are validation_failed with a pointer at the one that is wrong.

reminderTime is the earliest reminder. It is kept for clients that know only one reminder, and every write of the list rewrites it. Writing reminderTime on its own still works:

• on a to-do with no reminder list, it is the one reminder, exactly as before;
• on a to-do with a list, it replaces the earliest reminder and leaves the others.

Do not send reminderTime and reminders in one request.

What a date change does

The apps keep the three fields consistent with the date, and the API does the same, whichever field you change:

• Moving the date moves every before reminder with it. Fixed at reminders stay where they are.
• Clearing the date ("whenDate": null, parking in someday) drops the start and every before reminder. Fixed reminders and the length stay.
• Removing the time ("whenTime": null) drops the start and the length, and turns each before reminder into a fixed at reminder at the moment it would have rung. Nothing the user set disappears without a trace.

Repeating to-dos

A repeating to-do keeps its time, length and before reminders on every occurrence. When you complete one:

• the completed copy keeps the time and the length, and no reminders;
• the next occurrence keeps the start, the length and the before reminders, and a fixed reminder on the old day moves to the new day.

MCP

create_todo and update_todo take time, duration_min and reminders, with reminders written { "before_min": 15 } or { "at": "2026-10-11T20:00" }. The to-dos the tools return carry time, duration_min, time_text (16:00–17:00 (1h)) and each reminder.

Good to know

• A before reminder's moment is computed in plain wall-clock minutes. Across a daylight-saving change, a device in that zone can ring it an hour apart from the computed reminderTime. The stored reminder is the same.
• The deadline stays a date. It has no time.
• A length alone (no start) is a to-do that will take that long once it gets a time.

Next

• Dates and time zones for whenDate, deadline and whose day "today" is.
• Recurrence for repeat rules.