Docs
How HabitStats works, from your first habit to the API.
Getting started
- Sign up with your email and confirm it from the email we send.
- Install it on your phone (optional, but logging is quicker).
- Tap New habit, pick a type, a name and a colour.
- 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.
| Type | You log | For example |
|---|---|---|
| Checkbox | That you did it | Meditated, flossed |
| Number | An amount, in a unit you choose, with an optional target | Pages read, push-ups, glasses of water |
| Options | One of up to 20 options, each with its own colour | Climbing: gym or board; mood: good, okay, bad |
| Timer | How long: start and stop a timer, or enter a duration | Piano 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
- Tap Log on a habit, or tap a day in its heatmap to log or edit that day.
- You can log more than once a day; the heatmap shades darker with more.
- Every entry can have a note. Past days can be logged or fixed at any time.
- Timers keep running if you close the app, and you can stop them from any device. Cancel a timer to discard it.
- Each habit's History lists every entry, to edit or delete it.
Stats
Each habit's page has its stats. The controls:
- Period: group by day, week, month, quarter or year.
- Range: how far back to look.
- Rolling average: the average of the last few complete periods, drawn as a line over the bars.
- Measure: time (timers), total amount (numbers), entries, or days done.
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
- Time zone: decides which day an entry belongs to and when "today" starts.
- Week starts on: any day; weekly stats follow it.
- API tokens: create and revoke tokens for the API.
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.jsonAPI
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.
- In the app, go to Settings → API tokens and create a token.
- Copy it straight away; it's only shown once.
- 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).
| Request | Does |
|---|---|
GET /habits | Your habits, with their options |
POST /habits | Create a habit |
GET /entries?from=&to= | Entries between two dates |
POST /habits/{id}/entries | Log an entry |
POST /habits/{id}/timer/start, /stop | Start or stop a timer |
GET /habits/{id}/series | Totals per period, with a rolling average |
GET /habits/{id}/summary | Streaks 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.