the four date fields, and whose day the views use

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 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 for the full rule grammar.

The data model for what the views hold.
Reference for the routes.