openapi: 3.0.3
info:
  title: Habitify API v2
  description: |
    Welcome to our REST API. Use it to programmatically access your habit tracking data, build integrations, and automate workflows.

    ## Authentication
    All endpoints require authentication using an API key passed in the `X-API-Key` header.

    To generate your API key, open our app and go to **Settings > API**. Only one API key can be active at a time — generating a new key automatically revokes the previous one.

    > **Note:** API access requires a paid subscription and is not available on the free plan.

    ### Example Request
    ```
    curl -X GET https://api.habitify.me/v2/habits \
      -H "X-API-Key: YOUR_API_KEY"
    ```

    ## Rate Limiting
    We enforce a rate limit of **500 requests per minute** per account. If you exceed this limit, we will respond with a `429 Too Many Requests` status code. Wait for the rate limit window to reset before making additional requests.

    ## Versioning
    This is version 2 of our API. All endpoints are prefixed with `/v2`.
  version: 2.0.0
  contact:
    name: Habitify API Support
    url: https://habitify.me
  license:
    name: Proprietary
    url: https://habitify.me/terms
servers:
  - url: https://api.habitify.me/v2
    description: Production server
security:
  - ApiKeyTokenAuth: []
  - AccessTokenAuth: []
  - IdTokenAuth: []
components:
  securitySchemes:
    ApiKeyTokenAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key generated from our app (Settings > API). Only one key can be active at a time.
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token acquired from OAuth2
    IdTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ID token from Firebase Auth
  responses:
    UnauthorizedError:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
              message:
                type: string
                example: Invalid or missing authentication token
    NotFoundError:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not Found
              message:
                type: string
                example: The requested resource was not found
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Validation Error
              message:
                type: string
                example: Request validation failed
              details:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    message:
                      type: string
    RateLimitError:
      description: Rate limit exceeded (500 requests per minute)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Too Many Requests
              message:
                type: string
                example: Rate limit exceeded. Please wait before making more requests.
  schemas:
    Habit:
      description: Represents a habit you want to track. Contains all configuration including scheduling, goals, reminders, and categorization.
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the habit
        name:
          type: string
          description: Display name of the habit
        icon:
          type: string
          nullable: true
          description: Icon identifier used for visual display
        colorHex:
          type: string
          description: Hex color code for the habit (e.g., "#FF6B6B")
        type:
          description: |
            Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
          type: string
          enum:
            - good
            - bad
        description:
          type: string
          nullable: true
          description: Optional detailed description of the habit
        occurrence:
          description: |
            Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
          oneOf:
            - type: object
              description: The habit occurs every day.
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - daily
                  description: Indicates the habit occurs every day
            - type: object
              description: The habit occurs on specific days of the week.
              required:
                - type
                - days
              properties:
                type:
                  type: string
                  enum:
                    - weekDays
                  description: Indicates the habit occurs on selected weekdays
                days:
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 6
                    description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                  minItems: 1
                  maxItems: 7
                  uniqueItems: true
                  description: List of weekday numbers when the habit should occur
            - type: object
              description: The habit occurs on specific days of the month.
              required:
                - type
                - days
              properties:
                type:
                  type: string
                  enum:
                    - monthDays
                  description: Indicates the habit occurs on selected days of the month
                days:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                    maximum: 31
                    description: Day of the month (1-31)
                  minItems: 1
                  maxItems: 31
                  uniqueItems: true
                  description: List of month day numbers when the habit should occur
            - type: object
              description: The habit occurs at a fixed interval (e.g., every 3 days).
              required:
                - type
                - interval
              properties:
                type:
                  type: string
                  enum:
                    - intervalDays
                  description: Indicates the habit occurs at a fixed day interval
                interval:
                  type: integer
                  minimum: 1
                  description: Number of days between each occurrence
          discriminator:
            propertyName: type
        startDate:
          type: string
          format: date
          description: Date when the habit tracking begins (YYYY-MM-DD format)
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the habit was created
        isArchived:
          type: boolean
          description: Whether the habit is archived. Archived habits are hidden but their data is preserved.
        logMethod:
          description: |
            Determines how habit progress is tracked. - `manual`: You manually log progress through our app or API. - `auto`: Progress is automatically tracked via an integrated service (e.g., Apple Health, Fitbit, Strava).
          type: string
          enum:
            - manual
            - auto
        challengeId:
          type: string
          description: Identifier of the challenge this habit belongs to, if any
        reminders:
          description: Reminder configuration for a habit, including time-based triggers and habit stacking rules.
          type: object
          properties:
            timeTriggers:
              type: array
              description: List of time-based reminder triggers
              items:
                description: A time-based trigger that fires a reminder at a specific time, optionally restricted to certain days of the week.
                type: object
                properties:
                  time:
                    description: The time at which the reminder fires
                    type: object
                    required:
                      - hour
                      - minute
                    properties:
                      hour:
                        type: integer
                        minimum: 0
                        maximum: 23
                        description: Hour component in 24-hour format (0-23)
                      minute:
                        type: integer
                        minimum: 0
                        maximum: 59
                        description: Minute component (0-59)
                  occurrenceFilter:
                    type: object
                    description: Optional filter to restrict which days the reminder fires
                    properties:
                      weekDays:
                        type: array
                        description: Days of the week when the reminder should fire
                        items:
                          type: integer
                          enum:
                            - 1
                            - 2
                            - 3
                            - 4
                            - 5
                            - 6
                            - 7
                          description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                  showLiveActivity:
                    type: boolean
                    description: Whether to show a live activity notification (iOS only)
                  showAsAlarm:
                    type: boolean
                    description: Whether to display the reminder as an alarm-style notification
                required:
                  - time
            habitStacks:
              type: array
              description: List of habit stacking configurations that trigger this habit based on another habit's status
              items:
                description: A habit stacking rule that triggers a reminder for this habit based on the status of another habit.
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the habit stack. Required when updating an existing stack; omit when creating a new one.
                  conditionHabitId:
                    type: string
                    description: The ID of the habit whose status triggers this stack
                  type:
                    type: string
                    description: The condition type that triggers the stack (e.g., "completed", "failed")
                  timerType:
                    type: string
                    description: When to trigger the reminder (e.g., "immediately", "after")
                  timerDelaySecs:
                    type: integer
                    description: Delay in seconds before the stack triggers (used when timerType is "after")
                required:
                  - conditionHabitId
                  - type
                  - timerType
                  - timerDelaySecs
        endCondition:
          nullable: true
          description: Optional condition that determines when the habit automatically ends
          type: object
          discriminator:
            propertyName: type
            mapping:
              date: ./EndConditionSpecificDate.yaml
              streak: ./EndConditionStreak.yaml
              successPeriods: ./EndConditionSuccessPeriods.yaml
              totalLogValue: ./EndConditionTotalLogValue.yaml
          oneOf:
            - description: An end condition that causes the habit to end on a specific date.
              type: object
              required:
                - id
                - type
                - createdAt
                - date
                - isMet
              properties:
                id:
                  type: string
                  description: Unique identifier of the end condition
                type:
                  type: string
                  enum:
                    - date
                  description: Discriminator value indicating this is a date-based end condition
                createdAt:
                  type: string
                  format: date-time
                  description: Timestamp when the end condition was created
                isMet:
                  type: boolean
                  description: Whether the end condition has been satisfied
                date:
                  type: string
                  format: date
                  description: The date on which the habit ends (YYYY-MM-DD format)
            - description: An end condition that causes the habit to end after achieving a consecutive streak of a specified length.
              type: object
              required:
                - id
                - type
                - createdAt
                - periodType
                - streakLength
                - isMet
              properties:
                id:
                  type: string
                  description: Unique identifier of the end condition
                type:
                  type: string
                  enum:
                    - streak
                  description: Discriminator value indicating this is a streak-based end condition
                createdAt:
                  type: string
                  format: date-time
                  description: Timestamp when the end condition was created
                isMet:
                  type: boolean
                  description: Whether the end condition has been satisfied
                periodType:
                  description: The time period used to measure the streak (e.g., daily, weekly)
                  type: string
                  enum:
                    - daily
                    - weekly
                    - monthly
                    - yearly
                streakLength:
                  type: integer
                  description: Number of consecutive successful periods required to end the habit
            - description: An end condition that causes the habit to end after accumulating a specified number of successful periods (not necessarily consecutive).
              type: object
              required:
                - id
                - type
                - createdAt
                - periodType
                - totalPeriods
                - isMet
              properties:
                id:
                  type: string
                  description: Unique identifier of the end condition
                type:
                  type: string
                  enum:
                    - successPeriods
                  description: Discriminator value indicating this is a success-periods-based end condition
                createdAt:
                  type: string
                  format: date-time
                  description: Timestamp when the end condition was created
                isMet:
                  type: boolean
                  description: Whether the end condition has been satisfied
                periodType:
                  description: The time period used to count successes (e.g., daily, weekly)
                  type: string
                  enum:
                    - daily
                    - weekly
                    - monthly
                    - yearly
                totalPeriods:
                  type: integer
                  description: Total number of successful periods required to end the habit
            - description: An end condition that causes the habit to end after the cumulative logged value reaches a specified total.
              type: object
              required:
                - id
                - type
                - createdAt
                - totalLogValue
                - isMet
              properties:
                id:
                  type: string
                  description: Unique identifier of the end condition
                type:
                  type: string
                  enum:
                    - totalLogValue
                  description: Discriminator value indicating this is a total-log-value-based end condition
                createdAt:
                  type: string
                  format: date-time
                  description: Timestamp when the end condition was created
                isMet:
                  type: boolean
                  description: Whether the end condition has been satisfied
                totalLogValue:
                  type: number
                  description: Cumulative log value that must be reached to end the habit
        goals:
          type: array
          items:
            description: Represents a measurable goal attached to a habit, defining the target value, unit of measurement, and time period for tracking progress.
            type: object
            required:
              - id
              - createdAt
              - periodicity
              - value
              - unit
            properties:
              id:
                type: string
                description: Unique identifier of the goal
              createdAt:
                type: string
                format: date-time
                description: Timestamp when the goal was created
              periodicity:
                description: Time period over which the goal is measured
                type: string
                enum:
                  - daily
                  - weekly
                  - monthly
                  - yearly
              value:
                type: number
                description: Target value to achieve within the specified period (e.g., 5 for "5 km per day")
              unit:
                description: Unit of measurement for the goal value
                type: string
                enum:
                  - m
                  - kM
                  - ft
                  - yd
                  - mi
                  - floor
                  - L
                  - mL
                  - fl oz
                  - cup
                  - sec
                  - min
                  - hr
                  - ms
                  - kg
                  - g
                  - mg
                  - oz
                  - lb
                  - mcg
                  - J
                  - kJ
                  - kCal
                  - cal
                  - rep
                  - step
              isActive:
                type: boolean
                description: Whether the goal is currently active
          description: List of goals associated with this habit
        customUnitName:
          type: string
          nullable: true
          description: Custom unit name for measurable habits (e.g., "glasses" for water intake)
        areas:
          type: array
          items:
            description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
            type: object
            required:
              - id
              - name
              - createdAt
              - colorHex
              - icon
              - description
            properties:
              id:
                type: string
                description: Unique identifier of the area
              name:
                type: string
                description: Display name of the area
              colorHex:
                type: string
                description: Hex color code for the area (e.g., "#4ECDC4")
                nullable: true
              icon:
                type: string
                description: Icon identifier used for visual display
                nullable: true
              createdAt:
                type: string
                format: date-time
                description: Timestamp when the area was created
          description: Areas this habit is categorized under
        timeOfDays:
          type: array
          items:
            description: Represents a user-defined time-of-day period (e.g., "Morning", "Afternoon", "Evening") used to schedule when habits should be performed.
            type: object
            properties:
              id:
                type: string
                description: Unique identifier of the time-of-day period
              name:
                type: string
                description: Display name of the period (e.g., "Morning", "Afternoon", "Evening")
              icon:
                type: string
                description: Icon identifier for visual display
                nullable: true
              startTime:
                type: string
                format: time
                description: Start time of the period (HH:mm:ss format)
              endTime:
                type: string
                format: time
                description: End time of the period (HH:mm:ss format)
              colorHex:
                type: string
                description: Hex color code for visual display (e.g., "#FFD93D")
                nullable: true
            required:
              - id
              - name
              - startTime
              - endTime
              - colorHex
          description: Time-of-day periods when the habit should be performed
      required:
        - id
        - name
        - icon
        - colorHex
        - type
        - description
        - occurrence
        - startDate
        - createdAt
        - isArchived
        - logMethod
        - goals
    Type:
      description: |
        Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
      type: string
      enum:
        - good
        - bad
    Status:
      description: |
        Represents the completion status of a habit for a specific date. - `completed`: The habit was successfully completed for the day. - `skipped`: You intentionally skipped the habit. - `failed`: You marked the habit as failed. - `inprogress`: The habit has not yet been completed, skipped, or failed for the day.
      type: string
      enum:
        - completed
        - skipped
        - failed
        - inprogress
    LogMethod:
      description: |
        Determines how habit progress is tracked. - `manual`: You manually log progress through our app or API. - `auto`: Progress is automatically tracked via an integrated service (e.g., Apple Health, Fitbit, Strava).
      type: string
      enum:
        - manual
        - auto
    Goal:
      description: Represents a measurable goal attached to a habit, defining the target value, unit of measurement, and time period for tracking progress.
      type: object
      required:
        - id
        - createdAt
        - periodicity
        - value
        - unit
      properties:
        id:
          type: string
          description: Unique identifier of the goal
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the goal was created
        periodicity:
          description: Time period over which the goal is measured
          type: string
          enum:
            - daily
            - weekly
            - monthly
            - yearly
        value:
          type: number
          description: Target value to achieve within the specified period (e.g., 5 for "5 km per day")
        unit:
          description: Unit of measurement for the goal value
          type: string
          enum:
            - m
            - kM
            - ft
            - yd
            - mi
            - floor
            - L
            - mL
            - fl oz
            - cup
            - sec
            - min
            - hr
            - ms
            - kg
            - g
            - mg
            - oz
            - lb
            - mcg
            - J
            - kJ
            - kCal
            - cal
            - rep
            - step
        isActive:
          type: boolean
          description: Whether the goal is currently active
    Log:
      description: Represents a single log entry for a habit, recording the value tracked on a specific date.
      type: object
      required:
        - id
        - type
        - date
        - unitSymbol
        - value
      properties:
        id:
          type: string
          description: Unique identifier of the log entry
        type:
          description: |
            Indicates how the log entry was created. - `manual`: You manually recorded the value. - `auto`: The value was automatically recorded via an integrated service.
          type: string
          enum:
            - manual
            - auto
        date:
          type: string
          format: date
          description: Date of the log entry (YYYY-MM-DD format)
        unitSymbol:
          description: Unit of measurement for the logged value
          type: string
          enum:
            - m
            - kM
            - ft
            - yd
            - mi
            - floor
            - L
            - mL
            - fl oz
            - cup
            - sec
            - min
            - hr
            - ms
            - kg
            - g
            - mg
            - oz
            - lb
            - mcg
            - J
            - kJ
            - kCal
            - cal
            - rep
            - step
        value:
          type: number
          description: The recorded value for this log entry
        startDay:
          type: string
          format: date
          description: Start date of the tracking period for this log entry
        localLastModifiedDate:
          type: integer
          description: Timestamp of the last local modification (Unix epoch in milliseconds)
    Note:
      description: A note attached to a habit, optionally including text content, a mood level, and photos.
      type: object
      required:
        - id
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier of the note
        content:
          type: string
          nullable: true
          description: Text content of the note
        moodLevel:
          description: Mood level associated with the note
          nullable: true
          type: string
          enum:
            - veryLow
            - low
            - neutral
            - high
            - veryHigh
        photos:
          type: array
          items:
            type: string
            format: uri
          description: List of photo URLs attached to the note
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the note was created
    Reminder:
      description: Reminder configuration for a habit, including time-based triggers and habit stacking rules.
      type: object
      properties:
        timeTriggers:
          type: array
          description: List of time-based reminder triggers
          items:
            description: A time-based trigger that fires a reminder at a specific time, optionally restricted to certain days of the week.
            type: object
            properties:
              time:
                description: The time at which the reminder fires
                type: object
                required:
                  - hour
                  - minute
                properties:
                  hour:
                    type: integer
                    minimum: 0
                    maximum: 23
                    description: Hour component in 24-hour format (0-23)
                  minute:
                    type: integer
                    minimum: 0
                    maximum: 59
                    description: Minute component (0-59)
              occurrenceFilter:
                type: object
                description: Optional filter to restrict which days the reminder fires
                properties:
                  weekDays:
                    type: array
                    description: Days of the week when the reminder should fire
                    items:
                      type: integer
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
                        - 7
                      description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
              showLiveActivity:
                type: boolean
                description: Whether to show a live activity notification (iOS only)
              showAsAlarm:
                type: boolean
                description: Whether to display the reminder as an alarm-style notification
            required:
              - time
        habitStacks:
          type: array
          description: List of habit stacking configurations that trigger this habit based on another habit's status
          items:
            description: A habit stacking rule that triggers a reminder for this habit based on the status of another habit.
            type: object
            properties:
              id:
                type: string
                description: Unique identifier of the habit stack. Required when updating an existing stack; omit when creating a new one.
              conditionHabitId:
                type: string
                description: The ID of the habit whose status triggers this stack
              type:
                type: string
                description: The condition type that triggers the stack (e.g., "completed", "failed")
              timerType:
                type: string
                description: When to trigger the reminder (e.g., "immediately", "after")
              timerDelaySecs:
                type: integer
                description: Delay in seconds before the stack triggers (used when timerType is "after")
            required:
              - conditionHabitId
              - type
              - timerType
              - timerDelaySecs
    EndCondition:
      description: |
        Defines a condition under which a habit automatically ends. Supports multiple condition types: reaching a specific date, achieving a streak, completing a number of successful periods, or accumulating a total log value.
      type: object
      discriminator:
        propertyName: type
        mapping:
          date: ./EndConditionSpecificDate.yaml
          streak: ./EndConditionStreak.yaml
          successPeriods: ./EndConditionSuccessPeriods.yaml
          totalLogValue: ./EndConditionTotalLogValue.yaml
      oneOf:
        - description: An end condition that causes the habit to end on a specific date.
          type: object
          required:
            - id
            - type
            - createdAt
            - date
            - isMet
          properties:
            id:
              type: string
              description: Unique identifier of the end condition
            type:
              type: string
              enum:
                - date
              description: Discriminator value indicating this is a date-based end condition
            createdAt:
              type: string
              format: date-time
              description: Timestamp when the end condition was created
            isMet:
              type: boolean
              description: Whether the end condition has been satisfied
            date:
              type: string
              format: date
              description: The date on which the habit ends (YYYY-MM-DD format)
        - description: An end condition that causes the habit to end after achieving a consecutive streak of a specified length.
          type: object
          required:
            - id
            - type
            - createdAt
            - periodType
            - streakLength
            - isMet
          properties:
            id:
              type: string
              description: Unique identifier of the end condition
            type:
              type: string
              enum:
                - streak
              description: Discriminator value indicating this is a streak-based end condition
            createdAt:
              type: string
              format: date-time
              description: Timestamp when the end condition was created
            isMet:
              type: boolean
              description: Whether the end condition has been satisfied
            periodType:
              description: The time period used to measure the streak (e.g., daily, weekly)
              type: string
              enum:
                - daily
                - weekly
                - monthly
                - yearly
            streakLength:
              type: integer
              description: Number of consecutive successful periods required to end the habit
        - description: An end condition that causes the habit to end after accumulating a specified number of successful periods (not necessarily consecutive).
          type: object
          required:
            - id
            - type
            - createdAt
            - periodType
            - totalPeriods
            - isMet
          properties:
            id:
              type: string
              description: Unique identifier of the end condition
            type:
              type: string
              enum:
                - successPeriods
              description: Discriminator value indicating this is a success-periods-based end condition
            createdAt:
              type: string
              format: date-time
              description: Timestamp when the end condition was created
            isMet:
              type: boolean
              description: Whether the end condition has been satisfied
            periodType:
              description: The time period used to count successes (e.g., daily, weekly)
              type: string
              enum:
                - daily
                - weekly
                - monthly
                - yearly
            totalPeriods:
              type: integer
              description: Total number of successful periods required to end the habit
        - description: An end condition that causes the habit to end after the cumulative logged value reaches a specified total.
          type: object
          required:
            - id
            - type
            - createdAt
            - totalLogValue
            - isMet
          properties:
            id:
              type: string
              description: Unique identifier of the end condition
            type:
              type: string
              enum:
                - totalLogValue
              description: Discriminator value indicating this is a total-log-value-based end condition
            createdAt:
              type: string
              format: date-time
              description: Timestamp when the end condition was created
            isMet:
              type: boolean
              description: Whether the end condition has been satisfied
            totalLogValue:
              type: number
              description: Cumulative log value that must be reached to end the habit
    Area:
      description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
      type: object
      required:
        - id
        - name
        - createdAt
        - colorHex
        - icon
        - description
      properties:
        id:
          type: string
          description: Unique identifier of the area
        name:
          type: string
          description: Display name of the area
        colorHex:
          type: string
          description: Hex color code for the area (e.g., "#4ECDC4")
          nullable: true
        icon:
          type: string
          description: Icon identifier used for visual display
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the area was created
    UnitSymbol:
      description: |
        Symbol representing the unit of measurement for habit goals and logs. Covers distance, volume, time, weight, energy, and count-based units.
      type: string
      enum:
        - m
        - kM
        - ft
        - yd
        - mi
        - floor
        - L
        - mL
        - fl oz
        - cup
        - sec
        - min
        - hr
        - ms
        - kg
        - g
        - mg
        - oz
        - lb
        - mcg
        - J
        - kJ
        - kCal
        - cal
        - rep
        - step
    GoalPeriodicity:
      description: |
        The time period over which a goal is measured. - `daily`: Goal resets every day. - `weekly`: Goal resets every week. - `monthly`: Goal resets every month. - `yearly`: Goal resets every year.
      type: string
      enum:
        - daily
        - weekly
        - monthly
        - yearly
paths:
  /habits:
    get:
      tags:
        - Habits
      summary: Get all habits
      description: Retrieve a paginated list of your habits. Supports filtering by archived status, area, type, time of day, and scheduled date.
      parameters:
        - name: archived
          in: query
          schema:
            type: boolean
          description: Filter by archived status. If true, returns only archived habits. If false, returns only active habits.
        - name: areaId
          in: query
          schema:
            type: string
          description: Filter by area ID to return only habits assigned to a specific area
        - name: type
          in: query
          schema:
            description: |
              Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
            type: string
            enum:
              - good
              - bad
          description: Filter by habit type (good or bad)
        - name: timeOfDay
          in: query
          schema:
            type: string
          description: Filter by time-of-day period ID
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum number of habits to return per page
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of habits to skip for pagination
      responses:
        '200':
          description: A paginated list of habits
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      description: Represents a habit you want to track. Contains all configuration including scheduling, goals, reminders, and categorization.
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the habit
                        name:
                          type: string
                          description: Display name of the habit
                        icon:
                          type: string
                          nullable: true
                          description: Icon identifier used for visual display
                        colorHex:
                          type: string
                          description: Hex color code for the habit (e.g., "#FF6B6B")
                        type:
                          description: |
                            Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
                          type: string
                          enum:
                            - good
                            - bad
                        description:
                          type: string
                          nullable: true
                          description: Optional detailed description of the habit
                        occurrence:
                          description: |
                            Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
                          oneOf:
                            - type: object
                              description: The habit occurs every day.
                              required:
                                - type
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - daily
                                  description: Indicates the habit occurs every day
                            - type: object
                              description: The habit occurs on specific days of the week.
                              required:
                                - type
                                - days
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - weekDays
                                  description: Indicates the habit occurs on selected weekdays
                                days:
                                  type: array
                                  items:
                                    type: integer
                                    minimum: 0
                                    maximum: 6
                                    description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                                  minItems: 1
                                  maxItems: 7
                                  uniqueItems: true
                                  description: List of weekday numbers when the habit should occur
                            - type: object
                              description: The habit occurs on specific days of the month.
                              required:
                                - type
                                - days
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - monthDays
                                  description: Indicates the habit occurs on selected days of the month
                                days:
                                  type: array
                                  items:
                                    type: integer
                                    minimum: 1
                                    maximum: 31
                                    description: Day of the month (1-31)
                                  minItems: 1
                                  maxItems: 31
                                  uniqueItems: true
                                  description: List of month day numbers when the habit should occur
                            - type: object
                              description: The habit occurs at a fixed interval (e.g., every 3 days).
                              required:
                                - type
                                - interval
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - intervalDays
                                  description: Indicates the habit occurs at a fixed day interval
                                interval:
                                  type: integer
                                  minimum: 1
                                  description: Number of days between each occurrence
                          discriminator:
                            propertyName: type
                        startDate:
                          type: string
                          format: date
                          description: Date when the habit tracking begins (YYYY-MM-DD format)
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the habit was created
                        isArchived:
                          type: boolean
                          description: Whether the habit is archived. Archived habits are hidden but their data is preserved.
                        logMethod:
                          description: |
                            Determines how habit progress is tracked. - `manual`: You manually log progress through our app or API. - `auto`: Progress is automatically tracked via an integrated service (e.g., Apple Health, Fitbit, Strava).
                          type: string
                          enum:
                            - manual
                            - auto
                        challengeId:
                          type: string
                          description: Identifier of the challenge this habit belongs to, if any
                        reminders:
                          description: Reminder configuration for a habit, including time-based triggers and habit stacking rules.
                          type: object
                          properties:
                            timeTriggers:
                              type: array
                              description: List of time-based reminder triggers
                              items:
                                description: A time-based trigger that fires a reminder at a specific time, optionally restricted to certain days of the week.
                                type: object
                                properties:
                                  time:
                                    description: The time at which the reminder fires
                                    type: object
                                    required:
                                      - hour
                                      - minute
                                    properties:
                                      hour:
                                        type: integer
                                        minimum: 0
                                        maximum: 23
                                        description: Hour component in 24-hour format (0-23)
                                      minute:
                                        type: integer
                                        minimum: 0
                                        maximum: 59
                                        description: Minute component (0-59)
                                  occurrenceFilter:
                                    type: object
                                    description: Optional filter to restrict which days the reminder fires
                                    properties:
                                      weekDays:
                                        type: array
                                        description: Days of the week when the reminder should fire
                                        items:
                                          type: integer
                                          enum:
                                            - 1
                                            - 2
                                            - 3
                                            - 4
                                            - 5
                                            - 6
                                            - 7
                                          description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                                  showLiveActivity:
                                    type: boolean
                                    description: Whether to show a live activity notification (iOS only)
                                  showAsAlarm:
                                    type: boolean
                                    description: Whether to display the reminder as an alarm-style notification
                                required:
                                  - time
                            habitStacks:
                              type: array
                              description: List of habit stacking configurations that trigger this habit based on another habit's status
                              items:
                                description: A habit stacking rule that triggers a reminder for this habit based on the status of another habit.
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: Unique identifier of the habit stack. Required when updating an existing stack; omit when creating a new one.
                                  conditionHabitId:
                                    type: string
                                    description: The ID of the habit whose status triggers this stack
                                  type:
                                    type: string
                                    description: The condition type that triggers the stack (e.g., "completed", "failed")
                                  timerType:
                                    type: string
                                    description: When to trigger the reminder (e.g., "immediately", "after")
                                  timerDelaySecs:
                                    type: integer
                                    description: Delay in seconds before the stack triggers (used when timerType is "after")
                                required:
                                  - conditionHabitId
                                  - type
                                  - timerType
                                  - timerDelaySecs
                        endCondition:
                          nullable: true
                          description: Optional condition that determines when the habit automatically ends
                          type: object
                          discriminator:
                            propertyName: type
                            mapping:
                              date: ./EndConditionSpecificDate.yaml
                              streak: ./EndConditionStreak.yaml
                              successPeriods: ./EndConditionSuccessPeriods.yaml
                              totalLogValue: ./EndConditionTotalLogValue.yaml
                          oneOf:
                            - description: An end condition that causes the habit to end on a specific date.
                              type: object
                              required:
                                - id
                                - type
                                - createdAt
                                - date
                                - isMet
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the end condition
                                type:
                                  type: string
                                  enum:
                                    - date
                                  description: Discriminator value indicating this is a date-based end condition
                                createdAt:
                                  type: string
                                  format: date-time
                                  description: Timestamp when the end condition was created
                                isMet:
                                  type: boolean
                                  description: Whether the end condition has been satisfied
                                date:
                                  type: string
                                  format: date
                                  description: The date on which the habit ends (YYYY-MM-DD format)
                            - description: An end condition that causes the habit to end after achieving a consecutive streak of a specified length.
                              type: object
                              required:
                                - id
                                - type
                                - createdAt
                                - periodType
                                - streakLength
                                - isMet
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the end condition
                                type:
                                  type: string
                                  enum:
                                    - streak
                                  description: Discriminator value indicating this is a streak-based end condition
                                createdAt:
                                  type: string
                                  format: date-time
                                  description: Timestamp when the end condition was created
                                isMet:
                                  type: boolean
                                  description: Whether the end condition has been satisfied
                                periodType:
                                  description: The time period used to measure the streak (e.g., daily, weekly)
                                  type: string
                                  enum:
                                    - daily
                                    - weekly
                                    - monthly
                                    - yearly
                                streakLength:
                                  type: integer
                                  description: Number of consecutive successful periods required to end the habit
                            - description: An end condition that causes the habit to end after accumulating a specified number of successful periods (not necessarily consecutive).
                              type: object
                              required:
                                - id
                                - type
                                - createdAt
                                - periodType
                                - totalPeriods
                                - isMet
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the end condition
                                type:
                                  type: string
                                  enum:
                                    - successPeriods
                                  description: Discriminator value indicating this is a success-periods-based end condition
                                createdAt:
                                  type: string
                                  format: date-time
                                  description: Timestamp when the end condition was created
                                isMet:
                                  type: boolean
                                  description: Whether the end condition has been satisfied
                                periodType:
                                  description: The time period used to count successes (e.g., daily, weekly)
                                  type: string
                                  enum:
                                    - daily
                                    - weekly
                                    - monthly
                                    - yearly
                                totalPeriods:
                                  type: integer
                                  description: Total number of successful periods required to end the habit
                            - description: An end condition that causes the habit to end after the cumulative logged value reaches a specified total.
                              type: object
                              required:
                                - id
                                - type
                                - createdAt
                                - totalLogValue
                                - isMet
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the end condition
                                type:
                                  type: string
                                  enum:
                                    - totalLogValue
                                  description: Discriminator value indicating this is a total-log-value-based end condition
                                createdAt:
                                  type: string
                                  format: date-time
                                  description: Timestamp when the end condition was created
                                isMet:
                                  type: boolean
                                  description: Whether the end condition has been satisfied
                                totalLogValue:
                                  type: number
                                  description: Cumulative log value that must be reached to end the habit
                        goals:
                          type: array
                          items:
                            description: Represents a measurable goal attached to a habit, defining the target value, unit of measurement, and time period for tracking progress.
                            type: object
                            required:
                              - id
                              - createdAt
                              - periodicity
                              - value
                              - unit
                            properties:
                              id:
                                type: string
                                description: Unique identifier of the goal
                              createdAt:
                                type: string
                                format: date-time
                                description: Timestamp when the goal was created
                              periodicity:
                                description: Time period over which the goal is measured
                                type: string
                                enum:
                                  - daily
                                  - weekly
                                  - monthly
                                  - yearly
                              value:
                                type: number
                                description: Target value to achieve within the specified period (e.g., 5 for "5 km per day")
                              unit:
                                description: Unit of measurement for the goal value
                                type: string
                                enum:
                                  - m
                                  - kM
                                  - ft
                                  - yd
                                  - mi
                                  - floor
                                  - L
                                  - mL
                                  - fl oz
                                  - cup
                                  - sec
                                  - min
                                  - hr
                                  - ms
                                  - kg
                                  - g
                                  - mg
                                  - oz
                                  - lb
                                  - mcg
                                  - J
                                  - kJ
                                  - kCal
                                  - cal
                                  - rep
                                  - step
                              isActive:
                                type: boolean
                                description: Whether the goal is currently active
                          description: List of goals associated with this habit
                        customUnitName:
                          type: string
                          nullable: true
                          description: Custom unit name for measurable habits (e.g., "glasses" for water intake)
                        areas:
                          type: array
                          items:
                            description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                            type: object
                            required:
                              - id
                              - name
                              - createdAt
                              - colorHex
                              - icon
                              - description
                            properties:
                              id:
                                type: string
                                description: Unique identifier of the area
                              name:
                                type: string
                                description: Display name of the area
                              colorHex:
                                type: string
                                description: Hex color code for the area (e.g., "#4ECDC4")
                                nullable: true
                              icon:
                                type: string
                                description: Icon identifier used for visual display
                                nullable: true
                              createdAt:
                                type: string
                                format: date-time
                                description: Timestamp when the area was created
                          description: Areas this habit is categorized under
                        timeOfDays:
                          type: array
                          items:
                            description: Represents a user-defined time-of-day period (e.g., "Morning", "Afternoon", "Evening") used to schedule when habits should be performed.
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier of the time-of-day period
                              name:
                                type: string
                                description: Display name of the period (e.g., "Morning", "Afternoon", "Evening")
                              icon:
                                type: string
                                description: Icon identifier for visual display
                                nullable: true
                              startTime:
                                type: string
                                format: time
                                description: Start time of the period (HH:mm:ss format)
                              endTime:
                                type: string
                                format: time
                                description: End time of the period (HH:mm:ss format)
                              colorHex:
                                type: string
                                description: Hex color code for visual display (e.g., "#FFD93D")
                                nullable: true
                            required:
                              - id
                              - name
                              - startTime
                              - endTime
                              - colorHex
                          description: Time-of-day periods when the habit should be performed
                      required:
                        - id
                        - name
                        - icon
                        - colorHex
                        - type
                        - description
                        - occurrence
                        - startDate
                        - createdAt
                        - isArchived
                        - logMethod
                        - goals
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '400':
          description: Bad request - invalid query parameters
        '401':
          description: Unauthorized - missing or invalid authentication
    post:
      tags:
        - Habits
      summary: Create a new habit
      description: Create a new habit with optional goal, reminders, end condition, and area assignments.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
              properties:
                name:
                  type: string
                  description: Display name of the habit
                type:
                  description: |
                    Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
                  type: string
                  enum:
                    - good
                    - bad
                description:
                  type: string
                  description: Optional detailed description of the habit
                occurrence:
                  description: |
                    Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
                  oneOf:
                    - type: object
                      description: The habit occurs every day.
                      required:
                        - type
                      properties:
                        type:
                          type: string
                          enum:
                            - daily
                          description: Indicates the habit occurs every day
                    - type: object
                      description: The habit occurs on specific days of the week.
                      required:
                        - type
                        - days
                      properties:
                        type:
                          type: string
                          enum:
                            - weekDays
                          description: Indicates the habit occurs on selected weekdays
                        days:
                          type: array
                          items:
                            type: integer
                            minimum: 0
                            maximum: 6
                            description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                          minItems: 1
                          maxItems: 7
                          uniqueItems: true
                          description: List of weekday numbers when the habit should occur
                    - type: object
                      description: The habit occurs on specific days of the month.
                      required:
                        - type
                        - days
                      properties:
                        type:
                          type: string
                          enum:
                            - monthDays
                          description: Indicates the habit occurs on selected days of the month
                        days:
                          type: array
                          items:
                            type: integer
                            minimum: 1
                            maximum: 31
                            description: Day of the month (1-31)
                          minItems: 1
                          maxItems: 31
                          uniqueItems: true
                          description: List of month day numbers when the habit should occur
                    - type: object
                      description: The habit occurs at a fixed interval (e.g., every 3 days).
                      required:
                        - type
                        - interval
                      properties:
                        type:
                          type: string
                          enum:
                            - intervalDays
                          description: Indicates the habit occurs at a fixed day interval
                        interval:
                          type: integer
                          minimum: 1
                          description: Number of days between each occurrence
                  discriminator:
                    propertyName: type
                startDate:
                  type: string
                  format: date
                  description: Date when habit tracking begins (YYYY-MM-DD format). Defaults to today.
                icon:
                  type: string
                  description: Icon identifier for visual display
                colorHex:
                  type: string
                  description: Hex color code for the habit (e.g., "#FF6B6B")
                customUnitName:
                  type: string
                  description: Custom unit name for measurable habits (e.g., "glasses")
                areaIds:
                  type: array
                  items:
                    type: string
                  description: Area IDs to assign the habit to
                timeOfDayIds:
                  type: array
                  items:
                    type: string
                  description: Time-of-day period IDs to assign the habit to
                goal:
                  description: Goal to create with the habit
                  type: object
                  required:
                    - periodicity
                    - value
                    - unit
                  properties:
                    periodicity:
                      description: |
                        The time period over which a goal is measured. - `daily`: Goal resets every day. - `weekly`: Goal resets every week. - `monthly`: Goal resets every month. - `yearly`: Goal resets every year.
                      type: string
                      enum:
                        - daily
                        - weekly
                        - monthly
                        - yearly
                    value:
                      type: number
                      description: Target value to achieve within the specified period
                    unit:
                      description: |
                        Symbol representing the unit of measurement for habit goals and logs. Covers distance, volume, time, weight, energy, and count-based units.
                      type: string
                      enum:
                        - m
                        - kM
                        - ft
                        - yd
                        - mi
                        - floor
                        - L
                        - mL
                        - fl oz
                        - cup
                        - sec
                        - min
                        - hr
                        - ms
                        - kg
                        - g
                        - mg
                        - oz
                        - lb
                        - mcg
                        - J
                        - kJ
                        - kCal
                        - cal
                        - rep
                        - step
                reminders:
                  description: Reminders to create with the habit
                  type: object
                  properties:
                    timeTriggers:
                      type: array
                      description: List of time-based reminder triggers to set
                      items:
                        type: object
                        properties:
                          time:
                            description: Represents a time of day using 24-hour format with hour and minute components.
                            type: object
                            required:
                              - hour
                              - minute
                            properties:
                              hour:
                                type: integer
                                minimum: 0
                                maximum: 23
                                description: Hour component in 24-hour format (0-23)
                              minute:
                                type: integer
                                minimum: 0
                                maximum: 59
                                description: Minute component (0-59)
                          occurrenceFilter:
                            type: object
                            description: Optional filter to restrict which days the reminder fires
                            properties:
                              weekDays:
                                type: array
                                description: Days of the week when the reminder should fire
                                items:
                                  type: integer
                                  enum:
                                    - 1
                                    - 2
                                    - 3
                                    - 4
                                    - 5
                                    - 6
                                    - 7
                                  description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                          showLiveActivity:
                            type: boolean
                            description: Whether to show a live activity notification (iOS only)
                          showAsAlarm:
                            type: boolean
                            description: Whether to display the reminder as an alarm-style notification
                        required:
                          - time
                    habitStacks:
                      type: array
                      description: Habit stacking rules that trigger this habit based on another habit's status
                      items:
                        type: object
                        properties:
                          conditionHabitId:
                            type: string
                            description: The ID of the habit whose status triggers this stack
                          type:
                            type: string
                            enum:
                              - completed
                              - skipped
                              - failed
                              - reminder
                            description: The status of the condition habit that activates this stack
                          timerType:
                            type: string
                            enum:
                              - immediately
                              - after
                            description: When to trigger the stack (immediately or after a delay)
                          timerDelaySecs:
                            type: integer
                            description: Delay in seconds before triggering (required when timerType is "after")
                        required:
                          - conditionHabitId
                          - type
                          - timerType
                endCondition:
                  description: End condition to create with the habit
                  type: object
                  discriminator:
                    propertyName: type
                    mapping:
                      date: ./EndConditionSpecificDateInput.yaml
                      streak: ./EndConditionStreakInput.yaml
                      successPeriods: ./EndConditionSuccessPeriodsInput.yaml
                      totalLogValue: ./EndConditionTotalLogValueInput.yaml
                  oneOf:
                    - description: Input payload for creating a date-based end condition.
                      type: object
                      required:
                        - type
                        - date
                      properties:
                        type:
                          type: string
                          enum:
                            - date
                          description: Discriminator value indicating this is a date-based end condition
                        date:
                          type: string
                          format: date
                          description: The date on which the habit should end (YYYY-MM-DD format)
                    - description: Input payload for creating a streak-based end condition.
                      type: object
                      required:
                        - type
                        - streakLength
                      properties:
                        type:
                          type: string
                          enum:
                            - streak
                          description: Discriminator value indicating this is a streak-based end condition
                        streakLength:
                          type: integer
                          description: Number of consecutive successful periods required to end the habit
                    - description: Input payload for creating a success-periods-based end condition.
                      type: object
                      required:
                        - type
                        - totalPeriods
                      properties:
                        type:
                          type: string
                          enum:
                            - successPeriods
                          description: Discriminator value indicating this is a success-periods-based end condition
                        totalPeriods:
                          type: integer
                          description: Total number of successful periods required to end the habit
                    - description: Input payload for creating a total-log-value-based end condition.
                      type: object
                      required:
                        - type
                        - totalLogValue
                      properties:
                        type:
                          type: string
                          enum:
                            - totalLogValue
                          description: Discriminator value indicating this is a total-log-value-based end condition
                        totalLogValue:
                          type: number
                          description: Cumulative log value that must be reached to end the habit
      responses:
        '201':
          description: Habit created successfully
          content:
            application/json:
              schema:
                description: Represents a habit you want to track. Contains all configuration including scheduling, goals, reminders, and categorization.
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the habit
                  name:
                    type: string
                    description: Display name of the habit
                  icon:
                    type: string
                    nullable: true
                    description: Icon identifier used for visual display
                  colorHex:
                    type: string
                    description: Hex color code for the habit (e.g., "#FF6B6B")
                  type:
                    description: |
                      Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
                    type: string
                    enum:
                      - good
                      - bad
                  description:
                    type: string
                    nullable: true
                    description: Optional detailed description of the habit
                  occurrence:
                    description: |
                      Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
                    oneOf:
                      - type: object
                        description: The habit occurs every day.
                        required:
                          - type
                        properties:
                          type:
                            type: string
                            enum:
                              - daily
                            description: Indicates the habit occurs every day
                      - type: object
                        description: The habit occurs on specific days of the week.
                        required:
                          - type
                          - days
                        properties:
                          type:
                            type: string
                            enum:
                              - weekDays
                            description: Indicates the habit occurs on selected weekdays
                          days:
                            type: array
                            items:
                              type: integer
                              minimum: 0
                              maximum: 6
                              description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                            minItems: 1
                            maxItems: 7
                            uniqueItems: true
                            description: List of weekday numbers when the habit should occur
                      - type: object
                        description: The habit occurs on specific days of the month.
                        required:
                          - type
                          - days
                        properties:
                          type:
                            type: string
                            enum:
                              - monthDays
                            description: Indicates the habit occurs on selected days of the month
                          days:
                            type: array
                            items:
                              type: integer
                              minimum: 1
                              maximum: 31
                              description: Day of the month (1-31)
                            minItems: 1
                            maxItems: 31
                            uniqueItems: true
                            description: List of month day numbers when the habit should occur
                      - type: object
                        description: The habit occurs at a fixed interval (e.g., every 3 days).
                        required:
                          - type
                          - interval
                        properties:
                          type:
                            type: string
                            enum:
                              - intervalDays
                            description: Indicates the habit occurs at a fixed day interval
                          interval:
                            type: integer
                            minimum: 1
                            description: Number of days between each occurrence
                    discriminator:
                      propertyName: type
                  startDate:
                    type: string
                    format: date
                    description: Date when the habit tracking begins (YYYY-MM-DD format)
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the habit was created
                  isArchived:
                    type: boolean
                    description: Whether the habit is archived. Archived habits are hidden but their data is preserved.
                  logMethod:
                    description: |
                      Determines how habit progress is tracked. - `manual`: You manually log progress through our app or API. - `auto`: Progress is automatically tracked via an integrated service (e.g., Apple Health, Fitbit, Strava).
                    type: string
                    enum:
                      - manual
                      - auto
                  challengeId:
                    type: string
                    description: Identifier of the challenge this habit belongs to, if any
                  reminders:
                    description: Reminder configuration for a habit, including time-based triggers and habit stacking rules.
                    type: object
                    properties:
                      timeTriggers:
                        type: array
                        description: List of time-based reminder triggers
                        items:
                          description: A time-based trigger that fires a reminder at a specific time, optionally restricted to certain days of the week.
                          type: object
                          properties:
                            time:
                              description: The time at which the reminder fires
                              type: object
                              required:
                                - hour
                                - minute
                              properties:
                                hour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                  description: Hour component in 24-hour format (0-23)
                                minute:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                                  description: Minute component (0-59)
                            occurrenceFilter:
                              type: object
                              description: Optional filter to restrict which days the reminder fires
                              properties:
                                weekDays:
                                  type: array
                                  description: Days of the week when the reminder should fire
                                  items:
                                    type: integer
                                    enum:
                                      - 1
                                      - 2
                                      - 3
                                      - 4
                                      - 5
                                      - 6
                                      - 7
                                    description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                            showLiveActivity:
                              type: boolean
                              description: Whether to show a live activity notification (iOS only)
                            showAsAlarm:
                              type: boolean
                              description: Whether to display the reminder as an alarm-style notification
                          required:
                            - time
                      habitStacks:
                        type: array
                        description: List of habit stacking configurations that trigger this habit based on another habit's status
                        items:
                          description: A habit stacking rule that triggers a reminder for this habit based on the status of another habit.
                          type: object
                          properties:
                            id:
                              type: string
                              description: Unique identifier of the habit stack. Required when updating an existing stack; omit when creating a new one.
                            conditionHabitId:
                              type: string
                              description: The ID of the habit whose status triggers this stack
                            type:
                              type: string
                              description: The condition type that triggers the stack (e.g., "completed", "failed")
                            timerType:
                              type: string
                              description: When to trigger the reminder (e.g., "immediately", "after")
                            timerDelaySecs:
                              type: integer
                              description: Delay in seconds before the stack triggers (used when timerType is "after")
                          required:
                            - conditionHabitId
                            - type
                            - timerType
                            - timerDelaySecs
                  endCondition:
                    nullable: true
                    description: Optional condition that determines when the habit automatically ends
                    type: object
                    discriminator:
                      propertyName: type
                      mapping:
                        date: ./EndConditionSpecificDate.yaml
                        streak: ./EndConditionStreak.yaml
                        successPeriods: ./EndConditionSuccessPeriods.yaml
                        totalLogValue: ./EndConditionTotalLogValue.yaml
                    oneOf:
                      - description: An end condition that causes the habit to end on a specific date.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - date
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - date
                            description: Discriminator value indicating this is a date-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          date:
                            type: string
                            format: date
                            description: The date on which the habit ends (YYYY-MM-DD format)
                      - description: An end condition that causes the habit to end after achieving a consecutive streak of a specified length.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - periodType
                          - streakLength
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - streak
                            description: Discriminator value indicating this is a streak-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          periodType:
                            description: The time period used to measure the streak (e.g., daily, weekly)
                            type: string
                            enum:
                              - daily
                              - weekly
                              - monthly
                              - yearly
                          streakLength:
                            type: integer
                            description: Number of consecutive successful periods required to end the habit
                      - description: An end condition that causes the habit to end after accumulating a specified number of successful periods (not necessarily consecutive).
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - periodType
                          - totalPeriods
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - successPeriods
                            description: Discriminator value indicating this is a success-periods-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          periodType:
                            description: The time period used to count successes (e.g., daily, weekly)
                            type: string
                            enum:
                              - daily
                              - weekly
                              - monthly
                              - yearly
                          totalPeriods:
                            type: integer
                            description: Total number of successful periods required to end the habit
                      - description: An end condition that causes the habit to end after the cumulative logged value reaches a specified total.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - totalLogValue
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - totalLogValue
                            description: Discriminator value indicating this is a total-log-value-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          totalLogValue:
                            type: number
                            description: Cumulative log value that must be reached to end the habit
                  goals:
                    type: array
                    items:
                      description: Represents a measurable goal attached to a habit, defining the target value, unit of measurement, and time period for tracking progress.
                      type: object
                      required:
                        - id
                        - createdAt
                        - periodicity
                        - value
                        - unit
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the goal
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the goal was created
                        periodicity:
                          description: Time period over which the goal is measured
                          type: string
                          enum:
                            - daily
                            - weekly
                            - monthly
                            - yearly
                        value:
                          type: number
                          description: Target value to achieve within the specified period (e.g., 5 for "5 km per day")
                        unit:
                          description: Unit of measurement for the goal value
                          type: string
                          enum:
                            - m
                            - kM
                            - ft
                            - yd
                            - mi
                            - floor
                            - L
                            - mL
                            - fl oz
                            - cup
                            - sec
                            - min
                            - hr
                            - ms
                            - kg
                            - g
                            - mg
                            - oz
                            - lb
                            - mcg
                            - J
                            - kJ
                            - kCal
                            - cal
                            - rep
                            - step
                        isActive:
                          type: boolean
                          description: Whether the goal is currently active
                    description: List of goals associated with this habit
                  customUnitName:
                    type: string
                    nullable: true
                    description: Custom unit name for measurable habits (e.g., "glasses" for water intake)
                  areas:
                    type: array
                    items:
                      description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                      type: object
                      required:
                        - id
                        - name
                        - createdAt
                        - colorHex
                        - icon
                        - description
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the area
                        name:
                          type: string
                          description: Display name of the area
                        colorHex:
                          type: string
                          description: Hex color code for the area (e.g., "#4ECDC4")
                          nullable: true
                        icon:
                          type: string
                          description: Icon identifier used for visual display
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the area was created
                    description: Areas this habit is categorized under
                  timeOfDays:
                    type: array
                    items:
                      description: Represents a user-defined time-of-day period (e.g., "Morning", "Afternoon", "Evening") used to schedule when habits should be performed.
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the time-of-day period
                        name:
                          type: string
                          description: Display name of the period (e.g., "Morning", "Afternoon", "Evening")
                        icon:
                          type: string
                          description: Icon identifier for visual display
                          nullable: true
                        startTime:
                          type: string
                          format: time
                          description: Start time of the period (HH:mm:ss format)
                        endTime:
                          type: string
                          format: time
                          description: End time of the period (HH:mm:ss format)
                        colorHex:
                          type: string
                          description: Hex color code for visual display (e.g., "#FFD93D")
                          nullable: true
                      required:
                        - id
                        - name
                        - startTime
                        - endTime
                        - colorHex
                    description: Time-of-day periods when the habit should be performed
                required:
                  - id
                  - name
                  - icon
                  - colorHex
                  - type
                  - description
                  - occurrence
                  - startDate
                  - createdAt
                  - isArchived
                  - logMethod
                  - goals
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '422':
          description: Validation error - input data failed validation
  /habits/journal:
    get:
      tags:
        - Habits
      summary: Get habit journal
      description: Retrieve all your habits with their completion status and progress for a specific date. This provides a daily journal view showing each habit's current streak, progress toward goals, and log information.
      operationId: getHabitsJournal
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
          description: Date to retrieve the journal for (YYYY-MM-DD format). Defaults to today based on your timezone.
          required: false
      responses:
        '200':
          description: Journal data with habits and their progress for the requested date
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the habit
                        name:
                          type: string
                          description: Display name of the habit
                        status:
                          description: |
                            Represents the completion status of a habit for a specific date. - `completed`: The habit was successfully completed for the day. - `skipped`: You intentionally skipped the habit. - `failed`: You marked the habit as failed. - `inprogress`: The habit has not yet been completed, skipped, or failed for the day.
                          type: string
                          enum:
                            - completed
                            - skipped
                            - failed
                            - inprogress
                        colorHex:
                          type: string
                          description: Hex color code of the habit
                          example: '#FF6B6B'
                        icon:
                          type: string
                          description: Icon identifier of the habit
                        timeOfDayIds:
                          type: array
                          items:
                            type: string
                          description: IDs of time-of-day periods assigned to this habit
                        type:
                          type: string
                          enum:
                            - good
                            - bad
                          description: Whether this is a habit to build (good) or break (bad)
                        currentStreak:
                          type: object
                          description: Current consecutive streak information
                          properties:
                            length:
                              type: integer
                              description: Number of consecutive successful periods
                              example: 7
                            unit:
                              type: string
                              enum:
                                - day
                              description: Unit of measurement for the streak
                        progress:
                          type: object
                          description: Progress toward the habit's goal for the current period
                          properties:
                            current:
                              type: number
                              description: Current accumulated value for the period
                            target:
                              type: number
                              description: Target value to reach for the period
                            unit:
                              type: string
                              description: Unit of measurement for the progress value
                              example: rep
                            periodicity:
                              description: |
                                The time period over which a goal is measured. - `daily`: Goal resets every day. - `weekly`: Goal resets every week. - `monthly`: Goal resets every month. - `yearly`: Goal resets every year.
                              type: string
                              enum:
                                - daily
                                - weekly
                                - monthly
                                - yearly
                        logInfo:
                          type: object
                          description: Information about how the habit is logged
                          properties:
                            type:
                              description: |
                                Indicates how the log entry was created. - `manual`: You manually recorded the value. - `auto`: The value was automatically recorded via an integrated service.
                              type: string
                              enum:
                                - manual
                                - auto
                example:
                  data:
                    - id: habit_123
                      name: Morning Run
                      status: completed
                      colorHex: '#FF6B6B'
                      icon: running
                      timeOfDayIds:
                        - morning_slot_id
                      type: good
                      currentStreak:
                        length: 7
                        unit: day
                      progress:
                        current: 5.2
                        target: 5
                        unit: km
                        periodicity: daily
                      logInfo:
                        type: manual
                    - id: habit_456
                      name: Read Book
                      status: inprogress
                      colorHex: '#4ECDC4'
                      icon: book
                      timeOfDayIds:
                        - evening_slot_id
                      type: good
                      currentStreak:
                        length: 3
                        unit: day
                      progress:
                        current: 0
                        target: 30
                        unit: min
                        periodicity: daily
                      logInfo:
                        type: manual
        '400':
          description: Request validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Validation Error
                  message:
                    type: string
                    example: Request validation failed
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
        '401':
          description: Authentication information is missing or invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
                  message:
                    type: string
                    example: Invalid or missing authentication token
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Internal server error
  /habits/{habitId}:
    get:
      tags:
        - Habits
      summary: Get a habit
      description: Retrieve the full details of a specific habit by its ID, including goals, reminders, areas, and configuration.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
      responses:
        '200':
          description: The habit details
          content:
            application/json:
              schema:
                description: Represents a habit you want to track. Contains all configuration including scheduling, goals, reminders, and categorization.
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the habit
                  name:
                    type: string
                    description: Display name of the habit
                  icon:
                    type: string
                    nullable: true
                    description: Icon identifier used for visual display
                  colorHex:
                    type: string
                    description: Hex color code for the habit (e.g., "#FF6B6B")
                  type:
                    description: |
                      Indicates whether a habit is something you want to build or break. A "good" habit is one you want to maintain or increase (e.g., exercise, reading). A "bad" habit is one you want to reduce or eliminate (e.g., smoking, excessive screen time).
                    type: string
                    enum:
                      - good
                      - bad
                  description:
                    type: string
                    nullable: true
                    description: Optional detailed description of the habit
                  occurrence:
                    description: |
                      Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
                    oneOf:
                      - type: object
                        description: The habit occurs every day.
                        required:
                          - type
                        properties:
                          type:
                            type: string
                            enum:
                              - daily
                            description: Indicates the habit occurs every day
                      - type: object
                        description: The habit occurs on specific days of the week.
                        required:
                          - type
                          - days
                        properties:
                          type:
                            type: string
                            enum:
                              - weekDays
                            description: Indicates the habit occurs on selected weekdays
                          days:
                            type: array
                            items:
                              type: integer
                              minimum: 0
                              maximum: 6
                              description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                            minItems: 1
                            maxItems: 7
                            uniqueItems: true
                            description: List of weekday numbers when the habit should occur
                      - type: object
                        description: The habit occurs on specific days of the month.
                        required:
                          - type
                          - days
                        properties:
                          type:
                            type: string
                            enum:
                              - monthDays
                            description: Indicates the habit occurs on selected days of the month
                          days:
                            type: array
                            items:
                              type: integer
                              minimum: 1
                              maximum: 31
                              description: Day of the month (1-31)
                            minItems: 1
                            maxItems: 31
                            uniqueItems: true
                            description: List of month day numbers when the habit should occur
                      - type: object
                        description: The habit occurs at a fixed interval (e.g., every 3 days).
                        required:
                          - type
                          - interval
                        properties:
                          type:
                            type: string
                            enum:
                              - intervalDays
                            description: Indicates the habit occurs at a fixed day interval
                          interval:
                            type: integer
                            minimum: 1
                            description: Number of days between each occurrence
                    discriminator:
                      propertyName: type
                  startDate:
                    type: string
                    format: date
                    description: Date when the habit tracking begins (YYYY-MM-DD format)
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the habit was created
                  isArchived:
                    type: boolean
                    description: Whether the habit is archived. Archived habits are hidden but their data is preserved.
                  logMethod:
                    description: |
                      Determines how habit progress is tracked. - `manual`: You manually log progress through our app or API. - `auto`: Progress is automatically tracked via an integrated service (e.g., Apple Health, Fitbit, Strava).
                    type: string
                    enum:
                      - manual
                      - auto
                  challengeId:
                    type: string
                    description: Identifier of the challenge this habit belongs to, if any
                  reminders:
                    description: Reminder configuration for a habit, including time-based triggers and habit stacking rules.
                    type: object
                    properties:
                      timeTriggers:
                        type: array
                        description: List of time-based reminder triggers
                        items:
                          description: A time-based trigger that fires a reminder at a specific time, optionally restricted to certain days of the week.
                          type: object
                          properties:
                            time:
                              description: The time at which the reminder fires
                              type: object
                              required:
                                - hour
                                - minute
                              properties:
                                hour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                  description: Hour component in 24-hour format (0-23)
                                minute:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                                  description: Minute component (0-59)
                            occurrenceFilter:
                              type: object
                              description: Optional filter to restrict which days the reminder fires
                              properties:
                                weekDays:
                                  type: array
                                  description: Days of the week when the reminder should fire
                                  items:
                                    type: integer
                                    enum:
                                      - 1
                                      - 2
                                      - 3
                                      - 4
                                      - 5
                                      - 6
                                      - 7
                                    description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                            showLiveActivity:
                              type: boolean
                              description: Whether to show a live activity notification (iOS only)
                            showAsAlarm:
                              type: boolean
                              description: Whether to display the reminder as an alarm-style notification
                          required:
                            - time
                      habitStacks:
                        type: array
                        description: List of habit stacking configurations that trigger this habit based on another habit's status
                        items:
                          description: A habit stacking rule that triggers a reminder for this habit based on the status of another habit.
                          type: object
                          properties:
                            id:
                              type: string
                              description: Unique identifier of the habit stack. Required when updating an existing stack; omit when creating a new one.
                            conditionHabitId:
                              type: string
                              description: The ID of the habit whose status triggers this stack
                            type:
                              type: string
                              description: The condition type that triggers the stack (e.g., "completed", "failed")
                            timerType:
                              type: string
                              description: When to trigger the reminder (e.g., "immediately", "after")
                            timerDelaySecs:
                              type: integer
                              description: Delay in seconds before the stack triggers (used when timerType is "after")
                          required:
                            - conditionHabitId
                            - type
                            - timerType
                            - timerDelaySecs
                  endCondition:
                    nullable: true
                    description: Optional condition that determines when the habit automatically ends
                    type: object
                    discriminator:
                      propertyName: type
                      mapping:
                        date: ./EndConditionSpecificDate.yaml
                        streak: ./EndConditionStreak.yaml
                        successPeriods: ./EndConditionSuccessPeriods.yaml
                        totalLogValue: ./EndConditionTotalLogValue.yaml
                    oneOf:
                      - description: An end condition that causes the habit to end on a specific date.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - date
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - date
                            description: Discriminator value indicating this is a date-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          date:
                            type: string
                            format: date
                            description: The date on which the habit ends (YYYY-MM-DD format)
                      - description: An end condition that causes the habit to end after achieving a consecutive streak of a specified length.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - periodType
                          - streakLength
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - streak
                            description: Discriminator value indicating this is a streak-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          periodType:
                            description: The time period used to measure the streak (e.g., daily, weekly)
                            type: string
                            enum:
                              - daily
                              - weekly
                              - monthly
                              - yearly
                          streakLength:
                            type: integer
                            description: Number of consecutive successful periods required to end the habit
                      - description: An end condition that causes the habit to end after accumulating a specified number of successful periods (not necessarily consecutive).
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - periodType
                          - totalPeriods
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - successPeriods
                            description: Discriminator value indicating this is a success-periods-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          periodType:
                            description: The time period used to count successes (e.g., daily, weekly)
                            type: string
                            enum:
                              - daily
                              - weekly
                              - monthly
                              - yearly
                          totalPeriods:
                            type: integer
                            description: Total number of successful periods required to end the habit
                      - description: An end condition that causes the habit to end after the cumulative logged value reaches a specified total.
                        type: object
                        required:
                          - id
                          - type
                          - createdAt
                          - totalLogValue
                          - isMet
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the end condition
                          type:
                            type: string
                            enum:
                              - totalLogValue
                            description: Discriminator value indicating this is a total-log-value-based end condition
                          createdAt:
                            type: string
                            format: date-time
                            description: Timestamp when the end condition was created
                          isMet:
                            type: boolean
                            description: Whether the end condition has been satisfied
                          totalLogValue:
                            type: number
                            description: Cumulative log value that must be reached to end the habit
                  goals:
                    type: array
                    items:
                      description: Represents a measurable goal attached to a habit, defining the target value, unit of measurement, and time period for tracking progress.
                      type: object
                      required:
                        - id
                        - createdAt
                        - periodicity
                        - value
                        - unit
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the goal
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the goal was created
                        periodicity:
                          description: Time period over which the goal is measured
                          type: string
                          enum:
                            - daily
                            - weekly
                            - monthly
                            - yearly
                        value:
                          type: number
                          description: Target value to achieve within the specified period (e.g., 5 for "5 km per day")
                        unit:
                          description: Unit of measurement for the goal value
                          type: string
                          enum:
                            - m
                            - kM
                            - ft
                            - yd
                            - mi
                            - floor
                            - L
                            - mL
                            - fl oz
                            - cup
                            - sec
                            - min
                            - hr
                            - ms
                            - kg
                            - g
                            - mg
                            - oz
                            - lb
                            - mcg
                            - J
                            - kJ
                            - kCal
                            - cal
                            - rep
                            - step
                        isActive:
                          type: boolean
                          description: Whether the goal is currently active
                    description: List of goals associated with this habit
                  customUnitName:
                    type: string
                    nullable: true
                    description: Custom unit name for measurable habits (e.g., "glasses" for water intake)
                  areas:
                    type: array
                    items:
                      description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                      type: object
                      required:
                        - id
                        - name
                        - createdAt
                        - colorHex
                        - icon
                        - description
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the area
                        name:
                          type: string
                          description: Display name of the area
                        colorHex:
                          type: string
                          description: Hex color code for the area (e.g., "#4ECDC4")
                          nullable: true
                        icon:
                          type: string
                          description: Icon identifier used for visual display
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the area was created
                    description: Areas this habit is categorized under
                  timeOfDays:
                    type: array
                    items:
                      description: Represents a user-defined time-of-day period (e.g., "Morning", "Afternoon", "Evening") used to schedule when habits should be performed.
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the time-of-day period
                        name:
                          type: string
                          description: Display name of the period (e.g., "Morning", "Afternoon", "Evening")
                        icon:
                          type: string
                          description: Icon identifier for visual display
                          nullable: true
                        startTime:
                          type: string
                          format: time
                          description: Start time of the period (HH:mm:ss format)
                        endTime:
                          type: string
                          format: time
                          description: End time of the period (HH:mm:ss format)
                        colorHex:
                          type: string
                          description: Hex color code for visual display (e.g., "#FFD93D")
                          nullable: true
                      required:
                        - id
                        - name
                        - startTime
                        - endTime
                        - colorHex
                    description: Time-of-day periods when the habit should be performed
                required:
                  - id
                  - name
                  - icon
                  - colorHex
                  - type
                  - description
                  - occurrence
                  - startDate
                  - createdAt
                  - isArchived
                  - logMethod
                  - goals
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
    put:
      tags:
        - Habits
      summary: Update a habit
      description: Update the properties of an existing habit. Only the fields provided in the request body are updated; omitted fields remain unchanged.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New display name for the habit
                description:
                  type: string
                  description: New description for the habit
                occurrence:
                  description: |
                    Defines the recurrence schedule for a habit. A habit can occur daily, on specific days of the week, on specific days of the month, or at a fixed interval of days.
                  oneOf:
                    - type: object
                      description: The habit occurs every day.
                      required:
                        - type
                      properties:
                        type:
                          type: string
                          enum:
                            - daily
                          description: Indicates the habit occurs every day
                    - type: object
                      description: The habit occurs on specific days of the week.
                      required:
                        - type
                        - days
                      properties:
                        type:
                          type: string
                          enum:
                            - weekDays
                          description: Indicates the habit occurs on selected weekdays
                        days:
                          type: array
                          items:
                            type: integer
                            minimum: 0
                            maximum: 6
                            description: Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)
                          minItems: 1
                          maxItems: 7
                          uniqueItems: true
                          description: List of weekday numbers when the habit should occur
                    - type: object
                      description: The habit occurs on specific days of the month.
                      required:
                        - type
                        - days
                      properties:
                        type:
                          type: string
                          enum:
                            - monthDays
                          description: Indicates the habit occurs on selected days of the month
                        days:
                          type: array
                          items:
                            type: integer
                            minimum: 1
                            maximum: 31
                            description: Day of the month (1-31)
                          minItems: 1
                          maxItems: 31
                          uniqueItems: true
                          description: List of month day numbers when the habit should occur
                    - type: object
                      description: The habit occurs at a fixed interval (e.g., every 3 days).
                      required:
                        - type
                        - interval
                      properties:
                        type:
                          type: string
                          enum:
                            - intervalDays
                          description: Indicates the habit occurs at a fixed day interval
                        interval:
                          type: integer
                          minimum: 1
                          description: Number of days between each occurrence
                  discriminator:
                    propertyName: type
                startDate:
                  type: string
                  format: date
                  description: New start date for the habit (YYYY-MM-DD format)
                icon:
                  type: string
                  description: New icon identifier
                colorHex:
                  type: string
                  description: New hex color code
                customUnitName:
                  type: string
                  description: New custom unit name for measurable habits
                areaIds:
                  type: array
                  items:
                    type: string
                  description: Area IDs to assign the habit to (replaces existing assignments)
                timeOfDayIds:
                  type: array
                  items:
                    type: string
                  description: Time-of-day period IDs to assign the habit to (replaces existing assignments)
                goal:
                  description: Goal to set for the habit
                  type: object
                  required:
                    - periodicity
                    - value
                    - unit
                  properties:
                    periodicity:
                      description: |
                        The time period over which a goal is measured. - `daily`: Goal resets every day. - `weekly`: Goal resets every week. - `monthly`: Goal resets every month. - `yearly`: Goal resets every year.
                      type: string
                      enum:
                        - daily
                        - weekly
                        - monthly
                        - yearly
                    value:
                      type: number
                      description: Target value to achieve within the specified period
                    unit:
                      description: |
                        Symbol representing the unit of measurement for habit goals and logs. Covers distance, volume, time, weight, energy, and count-based units.
                      type: string
                      enum:
                        - m
                        - kM
                        - ft
                        - yd
                        - mi
                        - floor
                        - L
                        - mL
                        - fl oz
                        - cup
                        - sec
                        - min
                        - hr
                        - ms
                        - kg
                        - g
                        - mg
                        - oz
                        - lb
                        - mcg
                        - J
                        - kJ
                        - kCal
                        - cal
                        - rep
                        - step
                reminders:
                  description: Reminders to set for the habit
                  type: object
                  properties:
                    timeTriggers:
                      type: array
                      description: List of time-based reminder triggers to set
                      items:
                        type: object
                        properties:
                          time:
                            description: Represents a time of day using 24-hour format with hour and minute components.
                            type: object
                            required:
                              - hour
                              - minute
                            properties:
                              hour:
                                type: integer
                                minimum: 0
                                maximum: 23
                                description: Hour component in 24-hour format (0-23)
                              minute:
                                type: integer
                                minimum: 0
                                maximum: 59
                                description: Minute component (0-59)
                          occurrenceFilter:
                            type: object
                            description: Optional filter to restrict which days the reminder fires
                            properties:
                              weekDays:
                                type: array
                                description: Days of the week when the reminder should fire
                                items:
                                  type: integer
                                  enum:
                                    - 1
                                    - 2
                                    - 3
                                    - 4
                                    - 5
                                    - 6
                                    - 7
                                  description: Day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday)
                          showLiveActivity:
                            type: boolean
                            description: Whether to show a live activity notification (iOS only)
                          showAsAlarm:
                            type: boolean
                            description: Whether to display the reminder as an alarm-style notification
                        required:
                          - time
                    habitStacks:
                      type: array
                      description: Habit stacking rules that trigger this habit based on another habit's status
                      items:
                        type: object
                        properties:
                          conditionHabitId:
                            type: string
                            description: The ID of the habit whose status triggers this stack
                          type:
                            type: string
                            enum:
                              - completed
                              - skipped
                              - failed
                              - reminder
                            description: The status of the condition habit that activates this stack
                          timerType:
                            type: string
                            enum:
                              - immediately
                              - after
                            description: When to trigger the stack (immediately or after a delay)
                          timerDelaySecs:
                            type: integer
                            description: Delay in seconds before triggering (required when timerType is "after")
                        required:
                          - conditionHabitId
                          - type
                          - timerType
                endCondition:
                  description: End condition to set for the habit
                  type: object
                  discriminator:
                    propertyName: type
                    mapping:
                      date: ./EndConditionSpecificDateInput.yaml
                      streak: ./EndConditionStreakInput.yaml
                      successPeriods: ./EndConditionSuccessPeriodsInput.yaml
                      totalLogValue: ./EndConditionTotalLogValueInput.yaml
                  oneOf:
                    - description: Input payload for creating a date-based end condition.
                      type: object
                      required:
                        - type
                        - date
                      properties:
                        type:
                          type: string
                          enum:
                            - date
                          description: Discriminator value indicating this is a date-based end condition
                        date:
                          type: string
                          format: date
                          description: The date on which the habit should end (YYYY-MM-DD format)
                    - description: Input payload for creating a streak-based end condition.
                      type: object
                      required:
                        - type
                        - streakLength
                      properties:
                        type:
                          type: string
                          enum:
                            - streak
                          description: Discriminator value indicating this is a streak-based end condition
                        streakLength:
                          type: integer
                          description: Number of consecutive successful periods required to end the habit
                    - description: Input payload for creating a success-periods-based end condition.
                      type: object
                      required:
                        - type
                        - totalPeriods
                      properties:
                        type:
                          type: string
                          enum:
                            - successPeriods
                          description: Discriminator value indicating this is a success-periods-based end condition
                        totalPeriods:
                          type: integer
                          description: Total number of successful periods required to end the habit
                    - description: Input payload for creating a total-log-value-based end condition.
                      type: object
                      required:
                        - type
                        - totalLogValue
                      properties:
                        type:
                          type: string
                          enum:
                            - totalLogValue
                          description: Discriminator value indicating this is a total-log-value-based end condition
                        totalLogValue:
                          type: number
                          description: Cumulative log value that must be reached to end the habit
      responses:
        '200':
          description: Habit updated successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '422':
          description: Validation error - input data failed validation
    delete:
      tags:
        - Habits
      summary: Delete a habit
      description: Permanently delete a habit and all of its associated data, including logs, notes, goals, and reminders. This action cannot be undone.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to delete
      responses:
        '204':
          description: Habit deleted successfully
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
  /habits/{habitId}/archive:
    post:
      tags:
        - Habits
      summary: Archive a habit
      description: Archive a habit to hide it from the active habits list while preserving all of its data. Archived habits can still be viewed by filtering for archived habits.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to archive
      responses:
        '204':
          description: Habit archived successfully
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '409':
          description: Conflict - the habit is already archived
  /habits/{habitId}/statistics:
    get:
      tags:
        - Habits
      summary: Get habit statistics
      description: Retrieve aggregated statistics for a specific habit within an optional date range. Includes completion counts, skip and failure counts, total logged values, and an optional daily progress breakdown.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for the statistics range (YYYY-MM-DD format). Defaults to the habit's start date.
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for the statistics range (YYYY-MM-DD format). Defaults to today.
      responses:
        '200':
          description: Aggregated habit statistics for the requested period
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the habit
                      name:
                        type: string
                        description: Display name of the habit
                      type:
                        type: string
                        description: Habit type (good or bad)
                      totalLogs:
                        type: number
                        description: Sum of all logged values within the period
                      skips:
                        type: integer
                        description: Number of days the habit was skipped
                      fails:
                        type: integer
                        description: Number of days the habit was marked as failed
                      completions:
                        type: integer
                        description: Number of days the habit was completed successfully
                      unit:
                        type: object
                        description: Unit of measurement for the habit's logged values
                        properties:
                          id:
                            type: string
                            description: Unique identifier of the unit
                          name:
                            type: string
                            description: Display name of the unit
                          symbol:
                            type: string
                            description: Symbol for the unit (e.g., "km", "min")
                      periodicity:
                        type: string
                        description: Goal periodicity of the habit
                      avg:
                        type: number
                        description: Average logged value per day within the period
                      dailyProgress:
                        type: array
                        description: Day-by-day progress breakdown
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                              description: Date of the entry (YYYY-MM-DD format)
                            totalLog:
                              type: number
                              description: Total value logged for this date
                            status:
                              type: string
                              enum:
                                - completed
                                - failed
                                - skipped
                                - inprogress
                              description: Completion status of the habit for this date
        '400':
          description: Bad request - invalid query parameters
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
  /habits/{habitId}/logs:
    post:
      tags:
        - Habit Logs
      summary: Add a log entry
      description: Create a new log entry for a habit with a specific value and unit. Use this endpoint for measurable habits where you need to record a precise quantity.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to log
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - unitSymbol
                - value
              properties:
                unitSymbol:
                  description: |
                    Symbol representing the unit of measurement for habit goals and logs. Covers distance, volume, time, weight, energy, and count-based units.
                  type: string
                  enum:
                    - m
                    - kM
                    - ft
                    - yd
                    - mi
                    - floor
                    - L
                    - mL
                    - fl oz
                    - cup
                    - sec
                    - min
                    - hr
                    - ms
                    - kg
                    - g
                    - mg
                    - oz
                    - lb
                    - mcg
                    - J
                    - kJ
                    - kCal
                    - cal
                    - rep
                    - step
                value:
                  type: number
                  description: The value to log (e.g., 5 for "5 km", 30 for "30 minutes")
                targetDate:
                  type: string
                  format: date
                  description: Date to record the log for (YYYY-MM-DD format). Defaults to today.
      responses:
        '201':
          description: Log entry created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit log created successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '422':
          description: Validation error - input data failed validation
  /habits/{habitId}/logs/{logId}:
    delete:
      tags:
        - Habit Logs
      summary: Delete a log entry
      description: Permanently delete a specific log entry by its ID. This removes the recorded value from the habit's tracking history.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
        - name: logId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the log entry to delete
      responses:
        '200':
          description: Log entry deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit log removed successfully
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit or log entry not found
  /habits/{habitId}/logs/complete:
    post:
      tags:
        - Habit Logs
      summary: Mark habit as completed
      description: Mark a habit as completed for a specific date. The system automatically computes the appropriate log value based on the habit's goal or target.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to complete
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                targetDate:
                  type: string
                  format: date
                  description: Date to mark as completed (YYYY-MM-DD format). Defaults to today.
              example:
                targetDate: '2024-01-15'
      responses:
        '201':
          description: Habit marked as completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit marked as completed successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '409':
          description: Conflict - a log entry already exists for this date
  /habits/{habitId}/logs/failed:
    post:
      tags:
        - Habit Logs
      summary: Mark habit as failed
      description: Mark a habit as failed for a specific date. The system automatically records a failure log value.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to mark as failed
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                targetDate:
                  type: string
                  format: date
                  description: Date to mark as failed (YYYY-MM-DD format). Defaults to today.
              example:
                targetDate: '2024-01-15'
      responses:
        '201':
          description: Habit marked as failed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit marked as failed successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '409':
          description: Conflict - a log entry already exists for this date
  /habits/{habitId}/logs/skipped:
    post:
      tags:
        - Habit Logs
      summary: Mark habit as skipped
      description: Mark a habit as skipped for a specific date. Use this when you intentionally decide not to perform the habit for the day.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit to mark as skipped
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                targetDate:
                  type: string
                  format: date
                  description: Date to mark as skipped (YYYY-MM-DD format). Defaults to today.
              example:
                targetDate: '2024-01-15'
      responses:
        '201':
          description: Habit marked as skipped successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit marked as skipped successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '409':
          description: Conflict - a log entry already exists for this date
  /habits/{habitId}/logs/undo:
    post:
      tags:
        - Habit Logs
      summary: Undo habit logs for a day
      description: Remove all log entries for a habit on a specific date, effectively resetting the habit's status to in-progress for that day.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                targetDate:
                  type: string
                  format: date
                  description: Date to undo logs for (YYYY-MM-DD format). Defaults to today.
              example:
                targetDate: '2024-01-15'
      responses:
        '200':
          description: Habit progress undone successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Habit progress undone successfully
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
  /habits/{habitId}/notes:
    get:
      tags:
        - Habit Notes
      summary: Get notes for a habit
      description: Retrieve a paginated list of notes attached to a specific habit, ordered by creation date.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
      responses:
        '200':
          description: A list of notes for the habit
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      description: A note attached to a habit, optionally including text content, a mood level, and photos.
                      type: object
                      required:
                        - id
                        - createdAt
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the note
                        content:
                          type: string
                          nullable: true
                          description: Text content of the note
                        moodLevel:
                          description: Mood level associated with the note
                          nullable: true
                          type: string
                          enum:
                            - veryLow
                            - low
                            - neutral
                            - high
                            - veryHigh
                        photos:
                          type: array
                          items:
                            type: string
                            format: uri
                          description: List of photo URLs attached to the note
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the note was created
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
    post:
      tags:
        - Habit Notes
      summary: Add a note to a habit
      description: Create a new note for a habit. At least one of content, moodLevel, or photos must be provided.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                content:
                  type: string
                  nullable: true
                  description: Text content of the note
                moodLevel:
                  description: Mood level associated with the note
                  nullable: true
                  type: string
                  enum:
                    - veryLow
                    - low
                    - neutral
                    - high
                    - veryHigh
                photos:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: List of photo URLs to attach to the note
                  nullable: true
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                description: A note attached to a habit, optionally including text content, a mood level, and photos.
                type: object
                required:
                  - id
                  - createdAt
                properties:
                  id:
                    type: string
                    description: Unique identifier of the note
                  content:
                    type: string
                    nullable: true
                    description: Text content of the note
                  moodLevel:
                    description: Mood level associated with the note
                    nullable: true
                    type: string
                    enum:
                      - veryLow
                      - low
                      - neutral
                      - high
                      - veryHigh
                  photos:
                    type: array
                    items:
                      type: string
                      format: uri
                    description: List of photo URLs attached to the note
                    nullable: true
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the note was created
        '400':
          description: Bad request - at least one field must be provided
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit not found
        '422':
          description: Validation error - input data failed validation
  /habits/{habitId}/notes/{noteId}:
    put:
      tags:
        - Habit Notes
      summary: Update a note
      description: Update an existing note for a habit. At least one field must be provided. Only the fields included in the request body are updated.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
        - name: noteId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the note to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Updated text content of the note
                  nullable: true
                moodLevel:
                  description: Updated mood level for the note
                  nullable: true
                  type: string
                  enum:
                    - veryLow
                    - low
                    - neutral
                    - high
                    - veryHigh
                photos:
                  type: array
                  items:
                    type: string
                  description: Updated list of photo URLs
                  nullable: true
              minProperties: 1
            example:
              content: Updated note about my progress
              moodLevel: high
              photos:
                - https://example.com/photo1.jpg
      responses:
        '200':
          description: Note updated successfully
          content:
            application/json:
              schema:
                description: A note attached to a habit, optionally including text content, a mood level, and photos.
                type: object
                required:
                  - id
                  - createdAt
                properties:
                  id:
                    type: string
                    description: Unique identifier of the note
                  content:
                    type: string
                    nullable: true
                    description: Text content of the note
                  moodLevel:
                    description: Mood level associated with the note
                    nullable: true
                    type: string
                    enum:
                      - veryLow
                      - low
                      - neutral
                      - high
                      - veryHigh
                  photos:
                    type: array
                    items:
                      type: string
                      format: uri
                    description: List of photo URLs attached to the note
                    nullable: true
                  createdAt:
                    type: string
                    format: date-time
                    description: Timestamp when the note was created
        '400':
          description: Bad request - at least one field must be provided
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit or note not found
    delete:
      tags:
        - Habit Notes
      summary: Delete a note
      description: Permanently delete a note from a habit. This action cannot be undone.
      parameters:
        - name: habitId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the habit
        - name: noteId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the note to delete
      responses:
        '204':
          description: Note deleted successfully
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Habit or note not found
  /areas:
    get:
      tags:
        - Areas
      summary: Get all areas
      description: Retrieve a list of all your areas.
      responses:
        '200':
          description: A list of all areas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                      type: object
                      required:
                        - id
                        - name
                        - createdAt
                        - colorHex
                        - icon
                        - description
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the area
                        name:
                          type: string
                          description: Display name of the area
                        colorHex:
                          type: string
                          description: Hex color code for the area (e.g., "#4ECDC4")
                          nullable: true
                        icon:
                          type: string
                          description: Icon identifier used for visual display
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the area was created
        '401':
          description: Unauthorized - missing or invalid authentication
    post:
      tags:
        - Areas
      summary: Create an area
      description: Create a new area for organizing and categorizing habits.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Display name of the area (e.g., "Health", "Work")
                colorHex:
                  type: string
                  description: Hex color code for the area (e.g., "#4ECDC4")
                icon:
                  type: string
                  description: Icon identifier for visual display
      responses:
        '201':
          description: Area created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                    type: object
                    required:
                      - id
                      - name
                      - createdAt
                      - colorHex
                      - icon
                      - description
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the area
                      name:
                        type: string
                        description: Display name of the area
                      colorHex:
                        type: string
                        description: Hex color code for the area (e.g., "#4ECDC4")
                        nullable: true
                      icon:
                        type: string
                        description: Icon identifier used for visual display
                        nullable: true
                      createdAt:
                        type: string
                        format: date-time
                        description: Timestamp when the area was created
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '422':
          description: Validation error - input data failed validation
  /areas/{areaId}:
    get:
      tags:
        - Areas
      summary: Get a specific area
      description: Retrieve the details of a specific area by its ID.
      parameters:
        - name: areaId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the area
      responses:
        '200':
          description: The area details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                    type: object
                    required:
                      - id
                      - name
                      - createdAt
                      - colorHex
                      - icon
                      - description
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the area
                      name:
                        type: string
                        description: Display name of the area
                      colorHex:
                        type: string
                        description: Hex color code for the area (e.g., "#4ECDC4")
                        nullable: true
                      icon:
                        type: string
                        description: Icon identifier used for visual display
                        nullable: true
                      createdAt:
                        type: string
                        format: date-time
                        description: Timestamp when the area was created
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Area not found
    put:
      tags:
        - Areas
      summary: Update an area
      description: Update the properties of an existing area. Only the fields provided in the request body are updated.
      parameters:
        - name: areaId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the area to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New display name for the area
                colorHex:
                  type: string
                  description: New hex color code for the area
                icon:
                  type: string
                  description: New icon identifier for the area
      responses:
        '200':
          description: Area updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Represents an area used to categorize and organize habits into logical groups (e.g., "Health", "Work", "Personal").
                    type: object
                    required:
                      - id
                      - name
                      - createdAt
                      - colorHex
                      - icon
                      - description
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the area
                      name:
                        type: string
                        description: Display name of the area
                      colorHex:
                        type: string
                        description: Hex color code for the area (e.g., "#4ECDC4")
                        nullable: true
                      icon:
                        type: string
                        description: Icon identifier used for visual display
                        nullable: true
                      createdAt:
                        type: string
                        format: date-time
                        description: Timestamp when the area was created
        '400':
          description: Bad request - invalid input data
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Area not found
        '422':
          description: Validation error - input data failed validation
    delete:
      tags:
        - Areas
      summary: Delete an area
      description: Permanently delete an area. Habits assigned to this area will be unassigned but not deleted.
      parameters:
        - name: areaId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the area to delete
      responses:
        '204':
          description: Area deleted successfully
        '401':
          description: Unauthorized - missing or invalid authentication
        '404':
          description: Area not found
tags:
  - name: Habits
    description: Manage your habits — create, update, archive, and delete them
  - name: Habit Logs
    description: Track your progress by logging completions, failures, skips, and measured values
  - name: Habit Notes
    description: Attach notes with text, mood levels, and photos to your habits
  - name: Areas
    description: Organize your habits into areas for grouping and categorization
