Tasks

Tasks are the core unit of work in Pulse GTD. Each task can be categorized by urgency, importance, and state, assigned to projects and life buckets, and optionally shared with family members.

GET /api/v1/tasks

Retrieve a list of tasks for the authenticated user. Supports filtering by date range, completion status, and shared visibility.

Query Parameters

Parameter	Type	Description
`date`	`string`	Filter tasks for a specific date (ISO 8601 format, e.g. `2026-03-22`)
`date_from`	`string`	Start of date range filter (inclusive)
`date_to`	`string`	End of date range filter (inclusive)
`completed`	`boolean`	Filter by completion status
`shared`	`boolean`	Include tasks shared via family projects

Response

[
  {
    "id": "clx1a2b3c...",
    "title": "Review quarterly goals",
    "date": "2026-03-22",
    "time_label": "Morning",
    "minutes": 30,
    "urgency": "Urgent",
    "importance": "Important",
    "state": "Flow",
    "completed": false,
    "project_id": "clx4d5e6f...",
    "bucket_ids": ["clx7g8h9i..."],
    "is_review": false,
    "review_type": null,
    "sort_order": 0,
    "assignee_id": null,
    "createdAt": "2026-03-20T10:00:00.000Z",
    "updatedAt": "2026-03-20T10:00:00.000Z"
  }
]

POST /api/v1/tasks

Create a new task.

Request Body

{
  "title": "Review quarterly goals",
  "date": "2026-03-22",
  "time_label": "Morning",
  "minutes": 30,
  "urgency": "Urgent",
  "importance": "Important",
  "state": "Flow",
  "completed": false,
  "project_id": "clx4d5e6f...",
  "bucket_ids": ["clx7g8h9i..."],
  "is_review": false,
  "review_type": null,
  "sort_order": 0,
  "assignee_id": null
}

Fields

Field	Type	Required	Description
`title`	`string`	Yes	The task title
`date`	`string`	No	Scheduled date (ISO 8601)
`time_label`	`string`	No	Time of day label (e.g. `Morning`, `Afternoon`)
`minutes`	`number`	No	Estimated duration in minutes
`urgency`	`string`	No	One of: `Urgent`, `Not Urgent`, `Habit`
`importance`	`string`	No	One of: `Important`, `Not Important`, `Moved the Needle`
`state`	`string`	No	One of: `Flow`, `Quick`, `Easy`, `Personal`
`completed`	`boolean`	No	Whether the task is completed
`project_id`	`string`	No	Associated project ID
`bucket_ids`	`string[]`	No	Associated life bucket IDs
`is_review`	`boolean`	No	Whether this task is a review task
`review_type`	`string`	No	Review type if `is_review` is true
`sort_order`	`number`	No	Sort position within the task list
`assignee_id`	`string`	No	Family member ID to assign the task to

Response

{
  "id": "clx1a2b3c...",
  "title": "Review quarterly goals",
  "date": "2026-03-22",
  "time_label": "Morning",
  "minutes": 30,
  "urgency": "Urgent",
  "importance": "Important",
  "state": "Flow",
  "completed": false,
  "project_id": "clx4d5e6f...",
  "bucket_ids": ["clx7g8h9i..."],
  "is_review": false,
  "review_type": null,
  "sort_order": 0,
  "assignee_id": null,
  "createdAt": "2026-03-22T10:00:00.000Z",
  "updatedAt": "2026-03-22T10:00:00.000Z"
}

GET /api/v1/tasks/:id

Retrieve a single task by ID.

Response

{
  "id": "clx1a2b3c...",
  "title": "Review quarterly goals",
  "date": "2026-03-22",
  "time_label": "Morning",
  "minutes": 30,
  "urgency": "Urgent",
  "importance": "Important",
  "state": "Flow",
  "completed": false,
  "project_id": "clx4d5e6f...",
  "bucket_ids": ["clx7g8h9i..."],
  "is_review": false,
  "review_type": null,
  "sort_order": 0,
  "assignee_id": null,
  "createdAt": "2026-03-20T10:00:00.000Z",
  "updatedAt": "2026-03-20T10:00:00.000Z"
}

PATCH /api/v1/tasks/:id

Update an existing task. Only include the fields you want to change.

Request Body

{
  "title": "Review quarterly goals (updated)",
  "completed": true
}

All fields from the create endpoint are accepted. Only provided fields will be updated.

Response

Returns the updated task object.

DELETE /api/v1/tasks/:id

Permanently delete a task.

Response

{
  "success": true
}