init.Tasks openapi.json inittasks.com
[ contents ]

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. On a to-do with several reminders, the earliest.
completedAt ISO-8601 instant set by the server when you complete. Groups the completed view.

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.

On its day, a to-do can also have a start time (whenTime), a length (durationMin) and up to five reminders. All three are local wall-clock values too. See times, lengths and reminders.

A deadline does not schedule

People get this one wrong first. A to-do with a deadline and no whenDate is not in planned. It is in anytime until the deadline day, in today on that day, and in today's overdue block once the deadline has passed. That is a sorted one: a to-do still waiting in the inbox (no project, no date, no answer yet) stays in the inbox, and joins overdue once its deadline passes. A deadline is not an answer. See lists.

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 every /v1/views/* route.

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.

They all also take ?tz=, an IANA zone name; see below. GET /v1/views/completed (the old name logbook still answers) additionally takes from and to, both yyyy-MM-dd and inclusive: they keep only what was completed on those days (in ?tz), in the day groups and in containerCompleted alike. from after to is validation_failed.

Overdue

Overdue is deadline earlier than the day in play (a to-do still in the inbox included), 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/completed?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_completed tool (and its old name get_logbook) takes the same tz argument, defaulting to UTC. So does every MCP tool that reads a date phrase or needs "today", writes included: create_todo { when: "tomorrow", tz: "Europe/Amsterdam" } resolves tomorrow in Amsterdam. An unknown zone is refused there too. Read completedAt on each row for the exact instant.

Week start

GET /v1/settings reports weekStart as monday or sunday, the same setting the apps show. It orders the weekday columns of the date picker, and it decides which day next week suggests when you pick a date. 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.

Next