Habit AI

Track health and nutrition through the Habit AI REST API.

Setup (100% Free)

Habit AI is a completely free service — no subscription, no credit card, no usage limits.

1. 1. Create a free account at https://habitapp.ai (or download the free iOS app)
2. Go to Settings → API Keys → Create Key (free, up to 5 keys)
3. Store key in environment: INLINECODE0

All requests use:

• - Base URL: INLINECODE1
• Auth header: INLINECODE2
• Content-Type: INLINECODE3

Quick Reference

Action	Method	Endpoint
Log a meal	POST	INLINECODE4
Today's meals

GET | /meals?date=YYYY-MM-DD | | Daily nutrition | GET | /nutrition/daily?date=YYYY-MM-DD | | Weekly nutrition | GET | /nutrition/weekly?date=YYYY-MM-DD | | Log water (ml) | POST | /water | | Log weight (kg) | POST | /weight | | Log steps | POST | /steps | | Log meditation | POST | /meditation | | Journal entry | POST | /journal | | AI eating coach | POST | /coaches/eating | | AI mindfulness coach | POST | /coaches/mindfulness | | AI meditation coach | POST | /coaches/meditation | | Get profile | GET | /profile | | Update profile | PUT | /profile |

For full endpoint details (request/response schemas, all parameters), see references/api.md.

Logging Meals — The Right Way

⚠️ CRITICAL: Use the AI model to analyze food, then POST /meals with the EXACT structure below

Do NOT call /analyze/food-image or /analyze/meal-description — instead, use your own vision/language capabilities to analyze the food, then construct the exact JSON structure below and POST it to /meals.

Step 0: Check user profile for allergens/diet

Before analyzing, call GET /profile to check foodSensitivities and diet fields. Factor these into:

• - healthScore — lower the score if the meal contains ingredients the user is sensitive to
• healthScoreExplanation — mention the general nutritional pros/cons
• healthSensitivityExplanation — if the meal contains any of the user's allergens/sensitivities, explain which ingredients are problematic and why. Leave empty string if no sensitivities match.

Step 1: Analyze the food yourself

For photos: Look at the image and identify each ingredient, estimate portions, and calculate nutrition using USDA data.

For descriptions: Parse the meal description and calculate nutrition the same way.

Step 2: POST /meals with the EXACT structure

Every field matters. iOS reads from nutritionalSummary (nested object) — if it's missing, meals show as 0 calories.

CODEBLOCK0

Field Reference

Field	Type	Required	Description
INLINECODE25	string	Yes	Display name (e.g. "Chicken Caesar Salad"). Without this, the meal has no name in the app.
INLINECODE26

number | Yes | Total calories (kcal). Must be > 0. | | protein | number | Yes | Total protein in grams | | carbs | number | Yes | Total carbohydrates in grams | | fat | number | Yes | Total fat in grams | | fiber | number | Yes | Total fiber in grams | | sodium | number | Yes | Total sodium in milligrams | | sugar | number | Yes | Total sugar in grams | | healthScore | integer | Yes | 1-10. How healthy is this meal overall? (1=very unhealthy, 10=very healthy) | | mealType | string | Yes | One of: breakfast, lunch, dinner, snack | | analysisConfidenceLevel | integer | Yes | 1-10. How confident are you in the nutrition estimates? (1=wild guess, 10=exact data from packaging). For photo analysis use 6-8, for descriptions use 5-7. | | healthScoreExplanation | string | Yes | 1-2 sentence explanation of the nutritional pros/cons (e.g. "Good protein from chicken but high sodium from the sausage and dressing.") | | healthSensitivityExplanation | string | Yes | If the meal contains any of the user's allergens/food sensitivities (from profile), explain which ingredients are problematic. Empty string "" if no sensitivities match or user has none set. | | ingredients | array | Yes | Array of ingredient objects (see below) | | imageUrl | string | No | URL of the food photo. Get this from POST /meals/upload-image first (see below). | | dateScanned | string | No | ISO 8601 timestamp. Defaults to now if omitted. | | serving | number | No | Serving multiplier (defaults to 1.0) |

Ingredient Object

Each ingredient in the ingredients array must have:

Field	Type	Description
INLINECODE49	string	Ingredient name (e.g. "grilled chicken breast")
INLINECODE50

number | Calories for this ingredient's portion (kcal) |
| protein | number | Protein in grams |
| carbs | number | Carbs in grams |
| fat | number | Fat in grams |
| sugar | number | Sugar in grams |
| fiber | number | Fiber in grams |
| sodium | number | Sodium in milligrams |
| healthScore | integer | 1-10 health score for this specific ingredient |
| measurementType | string | Must be one of: grams, ounces, cups, spoons, servings. Use servings for pieces/slices/bowls/items. Use spoons for tablespoons/teaspoons. |
| measurementValue | number | Amount in the specified unit |

Important Rules

1. 1. All nutrition values must be numbers, not strings. "calories": 520 not INLINECODE68
2. Ingredient calories should sum to the total calories (approximately — within 5%)
3. mealName is mandatory — without it, the meal is invisible on iOS
4. healthScore is 1-10 integer — use your judgment (fast food = 2-4, home-cooked balanced = 6-8, raw salad = 9-10)
5. analysisConfidenceLevel is 1-10 integer — be honest about uncertainty
6. Sodium is in milligrams, everything else is in grams (except calories in kcal)

Uploading a meal photo (thumbnail)

If you have a food photo, upload it first to get a URL:

CODEBLOCK1

Returns: INLINECODE72

Then pass imageUrl in your POST /meals call. You can also attach to an existing meal:

CODEBLOCK2

Full flow with photo:

1. 1. POST /meals/upload-image with base64 photo → get INLINECODE75
2. INLINECODE76 with nutrition data + INLINECODE77

Other Workflows

Check remaining calories

1. 1. GET /nutrition/daily for today's totals
2. GET /profile for calorie goal
3. Subtract: INLINECODE80

Quick water log

CODEBLOCK3

Amount is in milliliters. 1 cup ≈ 237ml, 1 glass ≈ 250ml.

Notes

• - Dates default to today if omitted (uses user's timezone from profile)
• Water amount is in milliliters
• Weight is in kilograms (1 lb ≈ 0.4536 kg)
• Steps auto-calculate calories burned if profile has height/weight/gender
• Max 5 API keys per account