Docs

How HabitStats works, from your first habit to the API.

Getting started

  1. Sign up with your email and confirm it from the email we send.
  2. Install it on your phone (optional, but logging is quicker).
  3. Tap New habit, pick a type, a name and a colour.
  4. Log it: tap Log (or Start for a timer).

Habits

Each habit has one of four types. The type is set when you create it.

TypeYou logFor example
CheckboxThat you did itMeditated, flossed
NumberAn amount, in a unit you choose, with an optional targetPages read, push-ups, glasses of water
OptionsOne of up to 20 options, each with its own colourClimbing: gym or board; mood: good, okay, bad
TimerHow long: start and stop a timer, or enter a durationPiano practice, reading time

Name, description, unit, target and colour can be changed later. Use Reorder & archived on the home screen to change the order or bring back an archived habit. Archiving hides a habit and keeps its history; deleting removes it and its entries.

Logging

Stats

Each habit's page has its stats. The controls:

The current period is partial. It's drawn lighter and compared with the same point in the previous period, so you can see whether you are ahead or behind instead of a misleading drop.

Below the main chart: totals by weekday, by time of day (timers) and by option (options habits), plus current and best streak. Every chart can be shown as a table.

Settings

Import and export

Import

HabitHeat exports can be imported, keeping each habit, its options and every entry. There is no import button in the app yet: it's run for you on request. Other apps, or a CSV, can be loaded through the API by creating habits and entries.

Export

Everything you log can be read back through the API: your habits with GET /api/habits, and entries with GET /api/entries (up to 800 days per request). For example, everything since 2025 as JSON:

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.habitstats.app/api/habits" > habits.json
curl -H "Authorization: Bearer $TOKEN" \
  "https://app.habitstats.app/api/entries?from=2025-01-01&to=2026-12-31" > entries.json

API

Everything the app does goes through the same JSON API, so anything you can do in the app you can do from a script, Shortcuts, or an AI assistant.

  1. In the app, go to Settings → API tokens and create a token.
  2. Copy it straight away; it's only shown once.
  3. Send it on every request as Authorization: Bearer <token>.

Base URL: https://app.habitstats.app/api. The full reference, with every endpoint and field, is at https://app.habitstats.app/api/docs (OpenAPI schema at /api/openapi.json).

RequestDoes
GET /habitsYour habits, with their options
POST /habitsCreate a habit
GET /entries?from=&to=Entries between two dates
POST /habits/{id}/entriesLog an entry
POST /habits/{id}/timer/start, /stopStart or stop a timer
GET /habits/{id}/seriesTotals per period, with a rolling average
GET /habits/{id}/summaryStreaks and totals

Log 20 pages of reading for today (a number habit):

curl -X POST "https://app.habitstats.app/api/habits/$HABIT_ID/entries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"local_date": "2026-11-15", "value": 20}'

For the other types send nothing extra (checkbox), option_id (options) or duration_s in seconds (timer). note works on all of them. Entries made with a token are marked as coming from the API.