Skip to content
Day Planner

Planner

The planner is the auto-scheduler. POST /api/planner re-plans every auto-scheduled task and rewrites its future time blocks; GET /api/planner reports how much work is waiting. For the rules a run follows, see How the scheduler places work. Both endpoints need an API key or a signed-in session — see API keys. Requests without one get 401 Unauthorized; error responses carry an error message.

Run the planner

Section titled “Run the planner”

Re-plans your auto-scheduled tasks and replaces their future time blocks.

POST /api/planner

The run takes no parameters and no body.

What a run does

Section titled “What a run does”

A run covers the next 14 days in your timezone, falling back to Australia/Sydney when your stored zone is invalid. It looks at tasks with autoSchedule on, an estimateMinutes value, and a status other than completed, cancelled or archived. For each one it honours dueAt, startAfter, minSessionMinutes, maxSessionMinutes, cooldownMinutes and autoSplit, and schedules within the task’s schedule preference windows — or Mon–Fri 09:00–17:00 when the task has no preference. It also empties expired trash: archived tasks older than 30 days are permanently deleted.

A run replaces only the blocks it created and nobody has touched: future blocks of type task that are scheduled, unlocked and still marked as the planner’s own. Those get marked cancelled and rewritten. Everything else stays, and its remaining time counts towards the task’s estimate — blocks you placed or dragged into place, locked blocks, blocks that have already started, blocks in progress, and blocks with no task. Blocks belonging to a task you have switched to manual scheduling stay too. Auto-scheduled blocks of a task you have completed or cancelled are tidied up rather than re-planned. Concurrent runs for the same user queue behind each other instead of double-booking.

Response

Section titled “Response”

200 OK with the outcome of the run.

{
  "ok": true,
  "timezone": "Australia/Sydney",
  "tasksScheduled": 7,
  "tasksAtRisk": 1,
  "tasksUnscheduled": 2,
  "tasksOversized": 1,
  "atRiskTaskIds": ["c9f2a5d8-3e6b-4a1c-9d7f-2b5e8a0c3f64"],
  "unscheduledTaskIds": ["0a5d9c3b-7e1f-42a8-b6c4-9d2e8f0a1b37", "6f2b8e4a-1c5d-4b9a-a0e7-3c8f5d1b6a94"],
  "oversizedTaskIds": ["d4b9c2e7-5a83-4f16-9c0e-7b2d4a6e8f31"]
}
Field Values Meaning
ok true The run finished
timezone IANA zone The zone the run planned in
tasksScheduled integer Blocks the run created; a split task adds several
tasksAtRisk integer Tasks that are overdue or whose planned work ends after their due date
tasksUnscheduled integer Tasks with time left over that did not fit in the 14 days
tasksOversized integer Tasks whose estimate is longer than one working day
atRiskTaskIds array of string Ids of the at-risk tasks
unscheduledTaskIds array of string Ids of the tasks with time left over
oversizedTaskIds array of string Ids of the tasks worth splitting up or turning into projects

Read the blocks themselves through Time blocks.

Errors

Section titled “Errors”
  • 401 Unauthorized — no valid API key or session.

Check planner status

Section titled “Check planner status”

Counts what is waiting to be scheduled and what is already placed.

GET /api/planner

It takes no parameters.

Response

Section titled “Response”

200 OK with three counts.

{
  "pendingTasks": 4,
  "unscheduledTasks": 1,
  "scheduledBlocks": 9
}
Field Values Meaning
pendingTasks integer Tasks with status todo and autoSchedule on
unscheduledTasks integer Unfinished auto-scheduled tasks with no active block still to come
scheduledBlocks integer Blocks with status scheduled that have not ended

These counts tell you when another run of the planner would help.

Errors

Section titled “Errors”
  • 401 Unauthorized — no valid API key or session.

Example: run the planner

Section titled “Example: run the planner”

Fill the next fortnight in one call.

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

The response says how many blocks were placed and which tasks need attention; swap the method to GET to check the counts instead.

See also

Section titled “See also”