Buckets

Buckets represent life areas or categories (e.g. Health, Career, Relationships) that tasks, projects, and habits can be organized into. They provide a high-level view of where your time and energy are going.

GET /api/v1/buckets

List all life buckets for the authenticated user.

Response

[
  {
    "id": "clx7g8h9i...",
    "name": "Health",
    "color": "#10b981",
    "sort_order": 0,
    "createdAt": "2026-01-01T10:00:00.000Z",
    "updatedAt": "2026-01-01T10:00:00.000Z"
  }
]

POST /api/v1/buckets

Create a new life bucket.

Request Body

{
  "name": "Health",
  "color": "#10b981",
  "sort_order": 0
}

Fields

Field	Type	Required	Description
`name`	`string`	Yes	The bucket name
`color`	`string`	No	Hex color code for display
`sort_order`	`number`	No	Sort position in the bucket list

Response

Returns the created bucket object.

PATCH /api/v1/buckets/:id

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

Request Body

{
  "name": "Health & Fitness",
  "color": "#059669"
}

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

Response

Returns the updated bucket object.

DELETE /api/v1/buckets/:id

Permanently delete a life bucket. Tasks and projects associated with this bucket will have their bucket reference removed.

Response

{
  "success": true
}