# Times, lengths and reminders

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

| field | format | what it is |
|---|---|---|
| `whenTime` | `HH:mm`, 24-hour | the start. Only meaningful with a `whenDate` |
| `durationMin` | whole minutes, 5 to 1440 | the length. It can exist without a start |
| `reminders` | up to 5 | when to notify, each one `{ "before": minutes }` or `{ "at": "yyyy-MM-ddTHH:mm" }` |

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:

```bash
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:

```json
{ "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](/errors/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](/dates) for `whenDate`, `deadline` and whose day "today" is.
- [Recurrence](/recurrence) for repeat rules.