Create a new habit

curl --request POST \
  --url https://api.habitify.me/v2/habits \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "occurrence": {
    "type": "daily"
  },
  "startDate": "2023-12-25",
  "icon": "<string>",
  "colorHex": "<string>",
  "customUnitName": "<string>",
  "areaIds": [
    "<string>"
  ],
  "timeOfDayIds": [
    "<string>"
  ],
  "reminders": {
    "timeTriggers": [
      {
        "time": {
          "hour": 11,
          "minute": 29
        },
        "occurrenceFilter": {
          "weekDays": []
        },
        "showLiveActivity": true,
        "showAsAlarm": true
      }
    ],
    "habitStacks": [
      {
        "conditionHabitId": "<string>",
        "timerDelaySecs": 123
      }
    ]
  },
  "endCondition": {
    "type": "date",
    "date": "2023-12-25"
  }
}
'

import requests

url = "https://api.habitify.me/v2/habits"

payload = {
    "name": "<string>",
    "description": "<string>",
    "occurrence": { "type": "daily" },
    "startDate": "2023-12-25",
    "icon": "<string>",
    "colorHex": "<string>",
    "customUnitName": "<string>",
    "areaIds": ["<string>"],
    "timeOfDayIds": ["<string>"],
    "reminders": {
        "timeTriggers": [
            {
                "time": {
                    "hour": 11,
                    "minute": 29
                },
                "occurrenceFilter": { "weekDays": [] },
                "showLiveActivity": True,
                "showAsAlarm": True
            }
        ],
        "habitStacks": [
            {
                "conditionHabitId": "<string>",
                "timerDelaySecs": 123
            }
        ]
    },
    "endCondition": {
        "type": "date",
        "date": "2023-12-25"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    occurrence: {type: 'daily'},
    startDate: '2023-12-25',
    icon: '<string>',
    colorHex: '<string>',
    customUnitName: '<string>',
    areaIds: ['<string>'],
    timeOfDayIds: ['<string>'],
    reminders: {
      timeTriggers: [
        {
          time: {hour: 11, minute: 29},
          occurrenceFilter: {weekDays: []},
          showLiveActivity: true,
          showAsAlarm: true
        }
      ],
      habitStacks: [{conditionHabitId: '<string>', timerDelaySecs: 123}]
    },
    endCondition: {type: 'date', date: '2023-12-25'}
  })
};

fetch('https://api.habitify.me/v2/habits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.habitify.me/v2/habits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'occurrence' => [
        'type' => 'daily'
    ],
    'startDate' => '2023-12-25',
    'icon' => '<string>',
    'colorHex' => '<string>',
    'customUnitName' => '<string>',
    'areaIds' => [
        '<string>'
    ],
    'timeOfDayIds' => [
        '<string>'
    ],
    'reminders' => [
        'timeTriggers' => [
                [
                                'time' => [
                                                                'hour' => 11,
                                                                'minute' => 29
                                ],
                                'occurrenceFilter' => [
                                                                'weekDays' => [
                                                                                                                                
                                                                ]
                                ],
                                'showLiveActivity' => true,
                                'showAsAlarm' => true
                ]
        ],
        'habitStacks' => [
                [
                                'conditionHabitId' => '<string>',
                                'timerDelaySecs' => 123
                ]
        ]
    ],
    'endCondition' => [
        'type' => 'date',
        'date' => '2023-12-25'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.habitify.me/v2/habits"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.habitify.me/v2/habits")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.habitify.me/v2/habits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "icon": "<string>",
  "colorHex": "<string>",
  "type": "good",
  "description": "<string>",
  "occurrence": {
    "type": "daily"
  },
  "startDate": "2023-12-25",
  "createdAt": "2023-11-07T05:31:56Z",
  "isArchived": true,
  "logMethod": "manual",
  "goals": [
    {
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "periodicity": "daily",
      "value": 123,
      "unit": "m",
      "isActive": true
    }
  ],
  "challengeId": "<string>",
  "reminders": {
    "timeTriggers": [
      {
        "time": {
          "hour": 11,
          "minute": 29
        },
        "occurrenceFilter": {
          "weekDays": [
            1
          ]
        },
        "showLiveActivity": true,
        "showAsAlarm": true
      }
    ],
    "habitStacks": [
      {
        "conditionHabitId": "<string>",
        "type": "<string>",
        "timerType": "<string>",
        "timerDelaySecs": 123,
        "id": "<string>"
      }
    ]
  },
  "endCondition": {
    "id": "<string>",
    "type": "date",
    "createdAt": "2023-11-07T05:31:56Z",
    "isMet": true,
    "date": "2023-12-25"
  },
  "customUnitName": "<string>",
  "areas": [
    {
      "id": "<string>",
      "name": "<string>",
      "colorHex": "<string>",
      "icon": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "timeOfDays": [
    {
      "id": "<string>",
      "name": "<string>",
      "startTime": "<string>",
      "endTime": "<string>",
      "colorHex": "<string>",
      "icon": "<string>"
    }
  ]
}

POST

habits

Create a new habit

curl --request POST \
  --url https://api.habitify.me/v2/habits \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "occurrence": {
    "type": "daily"
  },
  "startDate": "2023-12-25",
  "icon": "<string>",
  "colorHex": "<string>",
  "customUnitName": "<string>",
  "areaIds": [
    "<string>"
  ],
  "timeOfDayIds": [
    "<string>"
  ],
  "reminders": {
    "timeTriggers": [
      {
        "time": {
          "hour": 11,
          "minute": 29
        },
        "occurrenceFilter": {
          "weekDays": []
        },
        "showLiveActivity": true,
        "showAsAlarm": true
      }
    ],
    "habitStacks": [
      {
        "conditionHabitId": "<string>",
        "timerDelaySecs": 123
      }
    ]
  },
  "endCondition": {
    "type": "date",
    "date": "2023-12-25"
  }
}
'

import requests

url = "https://api.habitify.me/v2/habits"

payload = {
    "name": "<string>",
    "description": "<string>",
    "occurrence": { "type": "daily" },
    "startDate": "2023-12-25",
    "icon": "<string>",
    "colorHex": "<string>",
    "customUnitName": "<string>",
    "areaIds": ["<string>"],
    "timeOfDayIds": ["<string>"],
    "reminders": {
        "timeTriggers": [
            {
                "time": {
                    "hour": 11,
                    "minute": 29
                },
                "occurrenceFilter": { "weekDays": [] },
                "showLiveActivity": True,
                "showAsAlarm": True
            }
        ],
        "habitStacks": [
            {
                "conditionHabitId": "<string>",
                "timerDelaySecs": 123
            }
        ]
    },
    "endCondition": {
        "type": "date",
        "date": "2023-12-25"
    }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    occurrence: {type: 'daily'},
    startDate: '2023-12-25',
    icon: '<string>',
    colorHex: '<string>',
    customUnitName: '<string>',
    areaIds: ['<string>'],
    timeOfDayIds: ['<string>'],
    reminders: {
      timeTriggers: [
        {
          time: {hour: 11, minute: 29},
          occurrenceFilter: {weekDays: []},
          showLiveActivity: true,
          showAsAlarm: true
        }
      ],
      habitStacks: [{conditionHabitId: '<string>', timerDelaySecs: 123}]
    },
    endCondition: {type: 'date', date: '2023-12-25'}
  })
};

fetch('https://api.habitify.me/v2/habits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.habitify.me/v2/habits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'description' => '<string>',
    'occurrence' => [
        'type' => 'daily'
    ],
    'startDate' => '2023-12-25',
    'icon' => '<string>',
    'colorHex' => '<string>',
    'customUnitName' => '<string>',
    'areaIds' => [
        '<string>'
    ],
    'timeOfDayIds' => [
        '<string>'
    ],
    'reminders' => [
        'timeTriggers' => [
                [
                                'time' => [
                                                                'hour' => 11,
                                                                'minute' => 29
                                ],
                                'occurrenceFilter' => [
                                                                'weekDays' => [
                                                                                                                                
                                                                ]
                                ],
                                'showLiveActivity' => true,
                                'showAsAlarm' => true
                ]
        ],
        'habitStacks' => [
                [
                                'conditionHabitId' => '<string>',
                                'timerDelaySecs' => 123
                ]
        ]
    ],
    'endCondition' => [
        'type' => 'date',
        'date' => '2023-12-25'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.habitify.me/v2/habits"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.habitify.me/v2/habits")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.habitify.me/v2/habits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"occurrence\": {\n    \"type\": \"daily\"\n  },\n  \"startDate\": \"2023-12-25\",\n  \"icon\": \"<string>\",\n  \"colorHex\": \"<string>\",\n  \"customUnitName\": \"<string>\",\n  \"areaIds\": [\n    \"<string>\"\n  ],\n  \"timeOfDayIds\": [\n    \"<string>\"\n  ],\n  \"reminders\": {\n    \"timeTriggers\": [\n      {\n        \"time\": {\n          \"hour\": 11,\n          \"minute\": 29\n        },\n        \"occurrenceFilter\": {\n          \"weekDays\": []\n        },\n        \"showLiveActivity\": true,\n        \"showAsAlarm\": true\n      }\n    ],\n    \"habitStacks\": [\n      {\n        \"conditionHabitId\": \"<string>\",\n        \"timerDelaySecs\": 123\n      }\n    ]\n  },\n  \"endCondition\": {\n    \"type\": \"date\",\n    \"date\": \"2023-12-25\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "icon": "<string>",
  "colorHex": "<string>",
  "type": "good",
  "description": "<string>",
  "occurrence": {
    "type": "daily"
  },
  "startDate": "2023-12-25",
  "createdAt": "2023-11-07T05:31:56Z",
  "isArchived": true,
  "logMethod": "manual",
  "goals": [
    {
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "periodicity": "daily",
      "value": 123,
      "unit": "m",
      "isActive": true
    }
  ],
  "challengeId": "<string>",
  "reminders": {
    "timeTriggers": [
      {
        "time": {
          "hour": 11,
          "minute": 29
        },
        "occurrenceFilter": {
          "weekDays": [
            1
          ]
        },
        "showLiveActivity": true,
        "showAsAlarm": true
      }
    ],
    "habitStacks": [
      {
        "conditionHabitId": "<string>",
        "type": "<string>",
        "timerType": "<string>",
        "timerDelaySecs": 123,
        "id": "<string>"
      }
    ]
  },
  "endCondition": {
    "id": "<string>",
    "type": "date",
    "createdAt": "2023-11-07T05:31:56Z",
    "isMet": true,
    "date": "2023-12-25"
  },
  "customUnitName": "<string>",
  "areas": [
    {
      "id": "<string>",
      "name": "<string>",
      "colorHex": "<string>",
      "icon": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ],
  "timeOfDays": [
    {
      "id": "<string>",
      "name": "<string>",
      "startTime": "<string>",
      "endTime": "<string>",
      "colorHex": "<string>",
      "icon": "<string>"
    }
  ]
}

Authorizations

X-API-Key

string

header

required

API key generated from our app (Settings > API). Only one key can be active at a time.

Body

application/json

name

string

required

Display name of the habit

type

enum<string>

required

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).

Available options:

good,

bad

description

string

Optional detailed description of the habit

occurrence

object

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.

Option 1
Option 2
Option 3
Option 4

Show child attributes

startDate

string<date>

Date when habit tracking begins (YYYY-MM-DD format). Defaults to today.

icon

string

Icon identifier for visual display

colorHex

string

Hex color code for the habit (e.g., "#FF6B6B")

customUnitName

string

Custom unit name for measurable habits (e.g., "glasses")

areaIds

string[]

Area IDs to assign the habit to

timeOfDayIds

string[]

Time-of-day period IDs to assign the habit to

goal

object

Goal to create with the habit

Show child attributes

reminders

object

Reminders to create with the habit

Show child attributes

endCondition

object

Input payload for creating a date-based end condition.

Option 1
Option 2
Option 3
Option 4

Show child attributes

Response

Habit created successfully

Represents a habit you want to track. Contains all configuration including scheduling, goals, reminders, and categorization.

string

required

Unique identifier of the habit

name

string

required

Display name of the habit

icon

string | null

required

Icon identifier used for visual display

colorHex

string

required

Hex color code for the habit (e.g., "#FF6B6B")

type

enum<string>

required

Available options:

good,

bad

description

string | null

required

Optional detailed description of the habit

occurrence

object

required

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.

Option 1
Option 2
Option 3
Option 4

Show child attributes

startDate

string<date>

required

Date when the habit tracking begins (YYYY-MM-DD format)

createdAt

string<date-time>

required

Timestamp when the habit was created

isArchived

boolean

required

Whether the habit is archived. Archived habits are hidden but their data is preserved.

logMethod

enum<string>

required

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).

Available options:

manual,

auto

goals

object[]

required

List of goals associated with this habit

Show child attributes

challengeId

string

Identifier of the challenge this habit belongs to, if any

reminders

object

Reminder configuration for a habit, including time-based triggers and habit stacking rules.

Show child attributes

endCondition

object

An end condition that causes the habit to end on a specific date.

Option 1
Option 2
Option 3
Option 4

Show child attributes

customUnitName

string | null

Custom unit name for measurable habits (e.g., "glasses" for water intake)

areas

object[]

Areas this habit is categorized under

Show child attributes

timeOfDays

object[]

Time-of-day periods when the habit should be performed

Show child attributes

Habits

Habit Logs

Habit Notes

Areas

Create a new habit

Authorizations

Body

Response