Schedule preferences

A schedule preference is a named set of weekly windows, such as “Working” or “Deep Work”. Link one to a task and the Planner places the task inside its windows instead of the default Mon–Fri 09:00–17:00. Every endpoint acts only on your own preferences and needs an API key or a signed-in session — see API keys. Requests without one get 401 Unauthorized; error responses carry an error message.

List schedule preferences

Lists your schedule preferences, highest priority first.

GET /api/schedule-preferences

It takes no parameters.

Response

200 OK with a JSON array of schedule preferences.

[
  {
    "id": "e7c3a9d2-5b1f-4e6a-8d4c-2a0f7b3e9c51",
    "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
    "name": "Working",
    "windows": [
      { "day": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00" }
    ],
    "priority": 0,
    "createdAt": "2026-09-28T21:40:12.005Z",
    "updatedAt": "2026-09-28T21:40:12.005Z"
  }
]

Each windows entry lists weekdays as numbers, 0 for Sunday through to 6 for Saturday, with 24-hour start and end times in your timezone.

Errors

• 401 Unauthorized — no valid API key or session.

Create a schedule preference

Creates a schedule preference.

POST /api/schedule-preferences

The body names the preference and the windows it allows.

Body fields

Name	Type	Required	Description
name	string	Yes	1–100 characters
windows	array	Yes	The weekly windows work may fall in; each window takes day, start and end
priority	integer	No	Higher sorts first in List schedule preferences; defaults to 0

Each window object takes these fields:

Name	Type	Required	Description
day	array of integer	Yes	The weekdays the window covers, 0 (Sunday) to 6 (Saturday); at least one
start	string	Yes	24-hour HH:MM time such as 09:00
end	string	Yes	24-hour HH:MM time such as 17:00, after start

Times must be valid HH:MM and end must be after start; anything else is rejected with 400, so a saved preference always has windows the planner can actually use. The same rules apply when updating a preference.

Response

201 Created with the new schedule preference.

{
  "id": "e7c3a9d2-5b1f-4e6a-8d4c-2a0f7b3e9c51",
  "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
  "name": "Working",
  "windows": [
    { "day": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00" }
  ],
  "priority": 0,
  "createdAt": "2026-09-30T22:41:09.223Z",
  "updatedAt": "2026-09-30T22:41:09.223Z"
}

Send the new id as a task’s schedulePreferenceId through Tasks to schedule the task inside these windows.

Errors

• 400 Bad Request — a field failed validation; details names the fields.
• 401 Unauthorized — no valid API key or session.

Update a schedule preference

Changes a schedule preference’s name, windows or priority.

PATCH /api/schedule-preferences/{id}

Every body field is optional, but the body must change something the preference has.

Body fields

Name	Type	Required	Description
name	string	No	1–100 characters
windows	array	No	The weekly windows work may fall in, in the same shape as Create a schedule preference
priority	integer	No	Higher sorts first in List schedule preferences

Response

200 OK with the updated schedule preference.

Errors

• 400 Bad Request — a field failed validation; details names the fields.
• 404 Not Found — no schedule preference of that id belongs to you.
• 401 Unauthorized — no valid API key or session.

Delete a schedule preference

Deletes a schedule preference for good.

DELETE /api/schedule-preferences/{id}

It takes no body.

Response

200 OK once the preference is gone.

{ "success": true }

Tasks that were linked to it fall back to the default Monday to Friday, 09:00 to 17:00 windows.

Errors

• 404 Not Found — no schedule preference of that id belongs to you.
• 401 Unauthorized — no valid API key or session.

Example: change your working hours

List your preferences, take the id of the Working one, and update its windows:

curl -X PATCH https://tasks.example.com/api/schedule-preferences/e7c3a9d2-5b1f-4e6a-8d4c-2a0f7b3e9c51 \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"windows":[{"day":[1,2,3,4,5],"start":"07:00","end":"15:00"}]}'

The response is 200 OK with the updated preference. Tasks linked to it are planned inside the new windows from the next run.

Example: create working hours

Add a nine-to-five window for the working week.

curl -X POST https://tasks.example.com/api/schedule-preferences \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"name":"Working","windows":[{"day":[1,2,3,4,5],"start":"09:00","end":"17:00"}]}'

The response is 201 Created with the preference; use its id as a task’s schedulePreferenceId to confine the task to these hours.

See also

• Scheduling and working hours: working hours in everyday use
• Planner: where the windows take effect
• How the scheduler places work: how windows shape the plan
• API keys: authenticate REST calls