Labels

Labels are coloured tags for tasks. Unlike a space or project, a label cuts across your work — “deep work”, “errand”, “waiting on someone” — and a task can carry several.

The web app shows labels on tasks and lists them in the sidebar, but you manage them through the REST API, either from a script or by asking an agent. Send an API key with every request.

Create a label

This request creates a label called “Deep work” in blue:

curl -X POST https://tasks.example.com/api/labels \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"name":"Deep work","color":"#3B82F6"}'

Day Planner returns the label and its id; use that id whenever you attach the label to a task. name is required and can be up to 100 characters. color is optional and must be a six-digit hex colour such as #3B82F6.

Rename or recolour a label

This request renames a label and changes its colour:

curl -X PATCH https://tasks.example.com/api/labels/LABEL_ID \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"name":"Focus","color":"#DC2626"}'

Send only the fields you want to change. Renaming keeps the label on every task that already has it.

Attach and remove labels on a task

This request sets the labels on a task:

curl -X PATCH https://tasks.example.com/api/tasks/TASK_ID \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"labelIds":["LABEL_ID","OTHER_LABEL_ID"]}'

labelIds always sets the full list, so the task ends up with exactly the labels you send. Add an id to attach a label, leave one out to remove it, and send an empty list to clear them all. Every id must be a label you own; Day Planner rejects the request if any id is missing or belongs to someone else.

Delete a label

This request deletes a label:

curl -X DELETE https://tasks.example.com/api/labels/LABEL_ID \
  -H "Authorization: Bearer dp_change-me"

Deleting a label takes it off every task at once; the tasks themselves stay. The response confirms the deletion.

Filter tasks by label

The sidebar’s Labels section lists each label with the number of tasks using it. Select one to open the tasks page filtered to that label, or choose a label from the All labels filter at the top of the tasks list. Scripts can filter the same way with a labelId query parameter on GET /api/tasks.

Constraints

A name runs from 1 to 100 characters and must be unique within your account: two people can each have a label called “Deep work”, but you can’t have two yourself. A duplicate create — or a rename onto an existing name — gets 409 Conflict.
A colour is optional and must be six hex digits with a leading #.
Only your own labels can go on your tasks.