# Dates and time zones

A to-do carries up to four moments, and they do different jobs.

| field | format | what it does |
|---|---|---|
| `whenDate` | `yyyy-MM-dd` | schedules the to-do. This is what puts it in a date view. |
| `deadline` | `yyyy-MM-dd` | when it is due. Surfaces as overdue. **Does not schedule.** |
| `reminderTime` | `yyyy-MM-ddTHH:mm` | a local wall-clock time for a notification. No zone, no seconds. |
| `completedAt` | ISO-8601 instant | set by the server when you complete. Groups the logbook. |

`whenDate` and `deadline` are calendar dates with no time and no zone. They mean the same day everywhere.

`reminderTime` carries no zone, by design. It is a wall-clock time on the user's device, so 09:00 stays 09:00 when they travel.

`completedAt` is the only true instant a client writes against, and the server sets it.

## A deadline does not schedule

People get this one wrong first. A to-do with a `deadline` and no `whenDate` is not in today or upcoming. It is in anytime, and it surfaces as overdue once the deadline passes.

To put a row on a day, set `whenDate`.

## Whose "today"?

Every date view needs a day to compute against, and **you should send it**.

```bash
curl -s "https://api.inittasks.com/v1/views/today?today=2026-09-16" \
  -H "Authorization: Bearer $INITTASKS_TOKEN"
```

`?today=` takes a `yyyy-MM-dd` date and is accepted by all six `/v1/views/*` routes.

**If you omit it, the server uses its own UTC date.** Not your zone, and not the user's. For a client east of UTC after midnight, or west of UTC before it, that is the wrong day, and the effect is silent: overdue is computed against the wrong boundary and today's bucket holds the wrong rows.

// Send `?today=` computed in the user's zone on every view request. There is no server-side setting for it, and the default is UTC rather than anything configured.

All six also take `?tz=`, an IANA zone name; see below. `GET /v1/views/logbook` additionally takes `from` and `to`, both `yyyy-MM-dd`.

## Overdue

Overdue is `deadline` earlier than the day in play, which is `?today=` when you send it and the server's UTC date when you do not. Active projects and subprojects with deadlines surface in the date views the same way.

## Which zone a completion counts in

A completion is an instant. Which *day* it lands on depends on a zone, and the views take one.

`?tz=` accepts an IANA zone name and **defaults to the literal `UTC`**, never to the server's environment.

```bash
curl -s "https://api.inittasks.com/v1/views/logbook?tz=Europe/Amsterdam" \
  -H "Authorization: Bearer $INITTASKS_TOKEN"
```

An unknown zone is [validation_failed](/errors/validation_failed) with a pointer, never a silent fallback.

It moves rows between days and between views. A 22:30Z completion is the 18th in UTC and the 19th in Amsterdam, and it moves in or out of `doneToday` accordingly. Send the user's zone on every view request, the same way you send `?today=`.

⚠ **The MCP `get_logbook` tool has no zone argument yet.** It reads the same day buckets and answers in its host's zone, so it can disagree with `GET /v1/views/logbook?tz=` for a completion near midnight. A zone parameter there is a follow-up. Until it lands, use the REST route when the boundary matters, and read `completedAt` on each row for the exact instant.

## Week start

`GET /v1/settings` reports `weekStart` as `monday` or `sunday`. It is presentation only: it orders the weekday columns of the date picker in the apps. It changes no view, no bucket and no count, and weekly recurrence stays Monday-anchored.

⚠ `PATCH /v1/settings` accepts `null` for `weekStart`, meaning "back to the default", but `GET` can only ever answer `monday` or `sunday`. A read-modify-write cycle therefore cannot round-trip a `null`, and does not need to: sending `"monday"` is the same outcome.

## Recurrence dates

`until` in a recurrence rule is a `yyyy-MM-dd` date, and it is the last date an occurrence may fall **on**, inclusive. See [REST and MCP](/rest-and-mcp) for the full rule grammar.

## Next

- [The data model](/data-model) for what the views hold.
- [Reference](/reference) for the routes.