> ## Documentation Index > Fetch the complete documentation index at: https://docs.habitify.me/llms.txt > Use this file to discover all available pages before exploring further. # Create a new habit > Create a new habit with optional goal, reminders, end condition, and area assignments. ## OpenAPI ````yaml https://static.habitify.me/Habitify%20API%20v2.json post /habits openapi: 3.1.1 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: [] tags: - name: Habits description: Manage your habits — create, update, archive, and delete them x-scalar-order: - habitify-api-v2/tag/habits/GET/habits - habitify-api-v2/tag/habits/POST/habits - habitify-api-v2/tag/habits/GET/habits/journal - habitify-api-v2/tag/habits/GET/habits/{habitId} - habitify-api-v2/tag/habits/PUT/habits/{habitId} - habitify-api-v2/tag/habits/DELETE/habits/{habitId} - habitify-api-v2/tag/habits/POST/habits/{habitId}/archive - habitify-api-v2/tag/habits/GET/habits/{habitId}/statistics - name: Habit Logs description: >- Track your progress by logging completions, failures, skips, and measured values x-scalar-order: - habitify-api-v2/tag/habit-logs/POST/habits/{habitId}/logs - habitify-api-v2/tag/habit-logs/DELETE/habits/{habitId}/logs/{logId} - habitify-api-v2/tag/habit-logs/POST/habits/{habitId}/logs/complete - habitify-api-v2/tag/habit-logs/POST/habits/{habitId}/logs/failed - habitify-api-v2/tag/habit-logs/POST/habits/{habitId}/logs/skipped - habitify-api-v2/tag/habit-logs/POST/habits/{habitId}/logs/undo - name: Habit Notes description: Attach notes with text, mood levels, and photos to your habits x-scalar-order: - habitify-api-v2/tag/habit-notes/GET/habits/{habitId}/notes - habitify-api-v2/tag/habit-notes/POST/habits/{habitId}/notes - habitify-api-v2/tag/habit-notes/PUT/habits/{habitId}/notes/{noteId} - habitify-api-v2/tag/habit-notes/DELETE/habits/{habitId}/notes/{noteId} - name: Areas description: Organize your habits into areas for grouping and categorization x-scalar-order: - habitify-api-v2/tag/areas/GET/areas - habitify-api-v2/tag/areas/POST/areas - habitify-api-v2/tag/areas/GET/areas/{areaId} - habitify-api-v2/tag/areas/PUT/areas/{areaId} - habitify-api-v2/tag/areas/DELETE/areas/{areaId} paths: /habits: 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 - 'null' 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 - 'null' 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: description: >- Optional condition that determines when the habit automatically ends type: - object - 'null' 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 - 'null' 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 - 'null' description: Hex color code for the area (e.g., "#4ECDC4") icon: type: - string - 'null' description: Icon identifier used for visual display 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 - 'null' description: Icon identifier for visual display 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 - 'null' description: Hex color code for visual display (e.g., "#FFD93D") 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 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.