Scheduling and working hours

Day Planner turns tasks into time blocks inside your working hours. It plans the next 14 days, and only when you run a plan — nothing is scheduled while you edit. This guide covers the settings that shape a plan, how to run one, and how to tidy up the blocks it creates.

Set working hours

Working hours are a schedule preference: a named set of weekly windows. Each window has:

day: the weekdays it covers, from 0 (Sunday) to 6 (Saturday)
start and end: 24-hour HH:MM times in your timezone

First-run setup creates a preference named Working from the hours you choose. Add as many preferences as you need — “Working”, “Evenings”, “Weekend” — with the schedule preferences API, which lists every option and lets you update or delete them later.

Give a task a preference by setting schedulePreferenceId on the task. A task with no preference is planned into Day Planner’s default windows: Monday to Friday, 09:00 to 17:00. Planning always happens in your account’s timezone, which you choose during setup.

Create a schedule preference

This request adds a “Weekend” preference with one window on Saturday morning.

curl -X POST https://tasks.example.com/api/schedule-preferences \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"name":"Weekend","windows":[{"day":[6],"start":"10:00","end":"13:00"}]}'

The response includes the new preference’s id; set a task’s schedulePreferenceId to that value to plan the task inside these windows. Windows whose end is at or before start, or whose times aren’t HH:MM, are ignored when planning.

Choose session sizes

Every task carries five scheduling settings:

estimateMinutes: how long the task takes, from 0 up to 960 minutes (16 hours). A task without an estimate is never scheduled. Anything longer than one working day (480 minutes) is accepted but flagged as oversized, so you can split it up or make it a project.
minSessionMinutes: the shortest block the planner creates, 1 to 60 minutes, default 5. A final block can be shorter when less work remains.
maxSessionMinutes: the longest block, 1 to 480 minutes, default 60 — short enough that you get up and move. Raise it per task for longer sittings; the scheduler never places a block past 8 hours.
cooldownMinutes: the gap the planner leaves between blocks of the same task, 0 to 1440 minutes, default 5.
autoSplit: on by default. When it’s off, the task gets a single block long enough for the whole estimate, and the planner waits for a gap big enough to hold it.

Together these decide how a big job is broken up and which gaps it can fit into. Two more settings shape placement: startAfter keeps a task’s blocks out of any earlier time, and schedulePreferenceId picks the working hours it may use.

Set session sizes on a task

This request caps one task’s blocks at 45 minutes, with a 15-minute break between them.

curl -X PATCH https://tasks.example.com/api/tasks/TASK_ID \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"maxSessionMinutes":45,"cooldownMinutes":15}'

The change takes effect at the next plan run. Adjust estimateMinutes, minSessionMinutes, maxSessionMinutes, cooldownMinutes or autoSplit to suit the work.

Run a plan

A plan runs only when you ask for one; editing a task never re-plans on its own. You can run or refresh a plan in two ways: over the REST API, or through a connected agent.

Run a plan over the REST API

This command re-plans the next 14 days using an API key.

curl -X POST -H "Authorization: Bearer dp_change-me" https://tasks.example.com/api/planner

The response reports the timezone it planned in, how many blocks it created, and the ids of tasks at risk or left unscheduled. Sending GET to the same endpoint returns counts of pending, unscheduled and scheduled work. Planner has the full response shape.

Run a plan from an agent

Ask your agent to run the run_scheduler tool — “re-plan my week” is enough. It re-plans, then returns the upcoming blocks with the same risk and overflow report. The tool takes no options; run_scheduler has the full contract, and Connect an agent shows how to set the MCP server up.

See your plan in the app

The Today page opens with four tiles: what you completed today, what’s due today, how many tasks are pending and how many are overdue. Under Schedule, the day shows as a time grid from 06:00 to 22:00 with each block placed at its time. Two lists follow: Needs scheduling, which shows auto-scheduled tasks with no block later today, with a hint such as “Add a time estimate” or “No free slot”. It compares against today’s blocks only, so a task already placed later in the week still appears here until that day., and Needs space, which shows tasks with no space or project.

The Week page shows seven columns from Monday to Sunday. Each day lists its time blocks with their start and end times, and the tasks due that day with their space colour. A block with no task is labelled “Blocked”.

Move, reorder and edit blocks

Re-planning replaces only the blocks it owns: task blocks that are still scheduled, unlocked and haven’t started. Locked blocks, blocks already started, in-progress and completed blocks, and blocks of other types (focus, manual, break) are kept and treated as busy time. Lock a block to keep it exactly where it is.

Move or lock a block

This request moves a block to 04:00–05:00 UTC on 5 October 2026 and locks it.

curl -X PATCH https://tasks.example.com/api/time-blocks/BLOCK_ID \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"startAt":"2026-10-05T04:00:00.000Z","endAt":"2026-10-05T05:00:00.000Z","locked":true}'

PATCH also accepts status (scheduled, in_progress, completed, cancelled) and sortOrder; send DELETE to the same URL to remove the block. Time blocks lists everything you can change.

Save a block order

The Today page shows the day as a time grid from 06:00 to 22:00. Drag any unlocked block to a new time — it lands on the nearest 5 minutes — or drag a task from Needs scheduling onto the grid to place it by hand (up to an hour, or 30 minutes without an estimate). Moving a block marks it manual, so the planner leaves it alone on the next run. If a move fails, the block snaps back and the page says so.

To keep a custom order, save it with the reorder endpoint.

curl -X PATCH https://tasks.example.com/api/time-blocks/reorder \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"orderedIds":["BLOCK_ID_1","BLOCK_ID_2"]}'

Each block’s sortOrder is set to its position in the list.

Complete work and re-plan

Marking a task completed, cancelled or archived takes it out of future plans. Mark a block in_progress when you start it: re-planning keeps it, treats its remaining time as busy, and counts its minutes towards the task’s estimate. Completed blocks are kept too.

When you finish early or something changes, run a plan again to fill the freed time. Each plan is rebuilt from the current moment, so unlocked blocks can move to a better slot.

When the plan overflows

The scheduler looks 14 days ahead and no further. Work that doesn’t fit is reported as unscheduled — at risk as well if it has a due date — and those tasks appear on the Today page under Needs scheduling with “No free slot”. To make room:

widen the working-hour windows, or give big tasks a preference with more hours
split a task into several tasks with their own estimates
turn autoSplit on so a long task can use several gaps
raise maxSessionMinutes so more of a gap gets used
finish or defer tasks to free days already planned

Run a plan again after any of these to see the result.