Habits

Habits represent recurring behaviors you want to build or maintain. Each habit can be tracked with daily logs, configured with cues and stacking, and tied to notification schedules.

GET /api/v1/habits

List all habits for the authenticated user.

Response

[
  {
    "id": "clx9a0b1c...",
    "name": "Morning meditation",
    "description": "10 minutes of mindfulness meditation",
    "importance": "High",
    "cue_time": "07:00",
    "cue_context": "After waking up",
    "habit_stack": "After brushing teeth",
    "frequency": "daily",
    "custom_days": null,
    "estimated_minutes": 10,
    "notify_enabled": true,
    "notify_time": "07:00",
    "bucket_id": "clx7g8h9i...",
    "createdAt": "2026-01-01T10:00:00.000Z",
    "updatedAt": "2026-03-20T10:00:00.000Z"
  }
]

POST /api/v1/habits

Create a new habit.

Request Body

{
  "name": "Morning meditation",
  "description": "10 minutes of mindfulness meditation",
  "importance": "High",
  "cue_time": "07:00",
  "cue_context": "After waking up",
  "habit_stack": "After brushing teeth",
  "frequency": "daily",
  "custom_days": null,
  "estimated_minutes": 10,
  "notify_enabled": true,
  "notify_time": "07:00",
  "bucket_id": "clx7g8h9i..."
}

Fields

Field	Type	Required	Description
`name`	`string`	Yes	The habit name
`description`	`string`	No	Detailed description of the habit
`importance`	`string`	No	One of: `Low`, `Medium`, `High`
`cue_time`	`string`	No	Time of day cue (HH:MM format)
`cue_context`	`string`	No	Contextual cue for the habit
`habit_stack`	`string`	No	Habit stacking anchor (e.g. "After brushing teeth")
`frequency`	`string`	No	One of: `daily`, `weekdays`, `weekends`, `weekly`, `custom`
`custom_days`	`string[]`	No	Required when frequency is `custom`. Array of day names.
`estimated_minutes`	`number`	No	Estimated time in minutes
`notify_enabled`	`boolean`	No	Whether notifications are enabled
`notify_time`	`string`	No	Notification time (HH:MM format)
`bucket_id`	`string`	No	Associated life bucket ID

Response

Returns the created habit object.

PATCH /api/v1/habits/:id

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

Request Body

{
  "importance": "Medium",
  "notify_enabled": false
}

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

Response

Returns the updated habit object.

DELETE /api/v1/habits/:id

Permanently delete a habit and all its associated logs.

Response

{
  "success": true
}

POST /api/v1/habits/:id/log

Log a habit completion or skip for a specific date.

Request Body

{
  "completed_date": "2026-03-22",
  "notes": "Felt great today",
  "skipped": false,
  "skip_reason": null
}

Fields

Field	Type	Required	Description
`completed_date`	`string`	Yes	The date of the log entry (ISO 8601 date)
`notes`	`string`	No	Optional notes about the session
`skipped`	`boolean`	No	Whether the habit was intentionally skipped
`skip_reason`	`string`	No	Reason for skipping (when `skipped` is true)

Response

Returns the created habit log object.