{"name":"CalorieFlow Agent API","description":"API specification and integration guide for CalorieFlow AI assistants.","manifest_url":"/api/agent/manifest","openapi_url":"/api/openapi.json","well_known_url":"/.well-known/agent-card","auth":{"pairing_flow":{"step1":"Generate a 12-character pairing code in the Web UI under Settings -> Connected AI Assistants.","step2":"Call POST /api/auth/agents/exchange with the pairing code to retrieve a persistent Bearer token."},"token_exchange_url":"/api/auth/agents/exchange","header_format":"Authorization: Bearer cfa_..."},"scopes":{"profile:read":"Read basic user profile (ID, username, email)","config:read":"Read user nutritional targets and corrections","config:write":"Write/update smartwatch correction and nutrient targets","diet:read":"Read daily food logs and nutrient intakes","diet:write":"Log food intake and update logs (supports idempotency via external_id)","weight:read":"Read weight history logs","weight:write":"Log/update reference or actual weights","expenditure:read":"Read smartwatch active/BMR calorie expenditure","expenditure:write":"Log/update smartwatch expenditure logs","foods:read":"Retrieve unique food databases and matching logs","recommendations:read":"Fetch AI-driven personalized meal recommendations"},"guidelines":{"date_format":"YYYY-MM-DD (e.g. 2026-06-08)","time_format":"HH:MM (e.g. 17:30)","idempotency":"Send a unique 'external_id' string inside food intake payloads to prevent double-logging on retry.","nutrition_estimation":"When logging food intake (POST /api/intake), if the user only provides the food name, the agent MUST use its knowledge or calculation to estimate and populate the calories (kcal_per_unit) and macronutrients (protein_per_unit, fat_per_unit, carb_per_unit) per unit size, rather than leaving them as zero."},"examples":{"exchange_pairing_code":{"method":"POST","path":"/api/auth/agents/exchange","body":{"code":"XXXX-XXXX-XXXX","client_name":"My Agent","client_type":"custom"}},"token_self_check":{"method":"GET","path":"/api/auth/agents/me","headers":{"Authorization":"Bearer cfa_..."}},"search_food":{"method":"GET","path":"/api/foods/search?q=banana&lang=en","headers":{"Authorization":"Bearer cfa_..."}},"log_food":{"method":"POST","path":"/api/intake","headers":{"Authorization":"Bearer cfa_..."},"body":{"date":"2026-06-08","meal_num":1,"meal_time":"08:30","food_name":"Oatmeal Porridge","total_weight":150.0,"unit_name":"g","unit_size":100.0,"kcal_per_unit":350.0,"category":"碳水/主食","external_id":"agent-20260608-0830-oat"}},"log_weight":{"method":"POST","path":"/api/weights","headers":{"Authorization":"Bearer cfa_..."},"body":{"date":"2026-06-08","actual_weight":75.5,"ref_weight":75.0}},"log_expenditure":{"method":"POST","path":"/api/expenditure","headers":{"Authorization":"Bearer cfa_..."},"body":{"date":"2026-06-08","raw_active_kcal":450.0,"raw_bmr_kcal":1800.0}},"get_recommendations":{"method":"GET","path":"/api/recommendations?date=2026-06-08&lang=zh&local_time=18:00","headers":{"Authorization":"Bearer cfa_..."}}}}