FatSecret API Skill#

What it does#

Use this skill when the user wants to:

• Search for foods or get nutritional information
• Look up a food by barcode
• Log food diary entries (create, edit, delete, copy)
• View daily or monthly food diary summaries
• Create and manage saved meals
• Search or browse recipes
• View or log exercises
• Track weight
• Manage a FatSecret user profile

All operations go through the FatSecret REST API via a Python helper script bundled with this skill.

Prerequisites#

1. The pyfatsecret Python package must be installed: pip install pyfatsecret
2. Environment variables must be set:
   • FATSECRET_CLIENT_ID — OAuth 2.0 client ID from https://platform.fatsecret.com/api/
   • FATSECRET_CLIENT_SECRET — OAuth 2.0 client secret

How to run commands#

Every operation is a single command:

text

python3 <skill-dir>/scripts/fs_runner.py <command> [--param value ...]

The script prints JSON to stdout on success and exits non-zero with an error message on failure.

Available operations#

Food search and lookup#

CommandRequired paramsOptional paramsDescriptionfoods_search``--query TEXT``--page INT, --max INT, --region, --languageSearch the food databasefoods_autocomplete``--expression TEXT``--max INT, --regionGet autocomplete suggestionsfood_get``--food_id IDGet detailed nutrition for a foodfood_get_v2``--food_id ID``--region, --languageGet detailed nutrition (v2)food_find_id_for_barcode``--barcode TEXT``--region, --languageFind a food by its GTIN-13 barcode

Example — search foods:

text

python3 scripts/fs_runner.py foods_search --query "chicken breast"

Example — get nutrition for a specific food:

text

python3 scripts/fs_runner.py food_get --food_id 4384

Food favorites (delegated)#

CommandRequired paramsOptional paramsDescriptionfood_add_favorite``--food_id ID``--serving_id, --number_of_unitsAdd a food to favoritesfood_delete_favorite``--food_id ID``--serving_id, --number_of_unitsRemove a food from favoritesfoods_get_favoritesList favorite foodsfoods_get_most_eaten``--mealList most eaten foodsfoods_get_recently_eaten``--mealList recently eaten foods

Food diary (delegated)#

CommandRequired paramsOptional paramsDescriptionfood_entry_create``--food_id, --food_entry_name, --serving_id, --number_of_units, --meal``--date YYYY-MM-DDLog a food diary entryfood_entry_edit``--food_entry_id``--food_entry_name, --serving_id, --number_of_units, --mealEdit a food diary entryfood_entry_delete``--food_entry_idDelete a food diary entryfood_entries_get``--food_entry_id or --date YYYY-MM-DDGet food diary entriesfood_entries_get_month``--date YYYY-MM-DDGet monthly food diary summaryfood_entries_copy``--from_date YYYY-MM-DD, --to_date YYYY-MM-DD``--mealCopy entries between datesfood_entries_copy_saved_meal``--saved_meal_id, --meal``--date YYYY-MM-DDCopy a saved meal to the diary

Example — log breakfast:

text

python3 scripts/fs_runner.py food_entry_create --food_id 4384 --food_entry_name "Chicken Breast" --serving_id 25381 --number_of_units 1.0 --meal breakfast

Saved meals (delegated)#

CommandRequired paramsOptional paramsDescriptionsaved_meal_create``--saved_meal_name``--saved_meal_description, --mealsCreate a saved mealsaved_meal_delete``--saved_meal_idDelete a saved mealsaved_meal_edit``--saved_meal_id``--saved_meal_name, --saved_meal_description, --mealsEdit a saved mealsaved_meal_get``--mealList saved mealssaved_meal_item_add``--saved_meal_id, --food_id, --saved_meal_item_name, --serving_id, --number_of_unitsAdd item to saved mealsaved_meal_item_delete``--saved_meal_item_idDelete saved meal itemsaved_meal_item_edit``--saved_meal_item_id``--saved_meal_item_name, --number_of_unitsEdit saved meal itemsaved_meal_items_get``--saved_meal_idList items in a saved meal

Recipes#

CommandRequired paramsOptional paramsDescriptionrecipes_search``--query TEXT``--recipe_type, --page INT, --max INTSearch recipesrecipe_get``--recipe_id IDGet recipe detailsrecipe_types_getList all recipe typesrecipes_add_favorite``--recipe_id IDAdd recipe to favoritesrecipes_delete_favorite``--recipe_id IDRemove recipe from favoritesrecipes_get_favoritesList favorite recipes

Example — search recipes:

text

python3 scripts/fs_runner.py recipes_search --query "low carb dinner"

Exercises (delegated)#

CommandRequired paramsOptional paramsDescriptionexercises_getList all exercise typesexercise_entries_get``--date YYYY-MM-DDGet exercise entries for a dayexercise_entries_get_month``--date YYYY-MM-DDGet monthly exercise summaryexercise_entries_commit_day``--date YYYY-MM-DDSave default exercises for a dayexercise_entries_save_template``--days BITS``--date YYYY-MM-DDSave exercise day as templateexercise_entry_edit``--shift_to_id, --shift_from_id, --minutes``--date, --shift_to_name, --shift_from_name, --kcalEdit exercise entry

Profile (delegated)#

CommandRequired paramsOptional paramsDescriptionprofile_create``--user_idCreate a new profileprofile_get_auth``--user_idGet auth info for a user

Weight (delegated)#

CommandRequired paramsOptional paramsDescriptionweight_update``--current_weight_kg FLOAT``--date, --weight_type, --height_type, --goal_weight_kg, --current_height_cm, --commentRecord weightweights_get_month``--date YYYY-MM-DDGet monthly weight log

Example — log weight:

text

python3 scripts/fs_runner.py weight_update --current_weight_kg 75.5

Output format#

• The script always prints JSON to stdout.
• Summarize the JSON for the user in a readable way (e.g. a table of foods with calories, a confirmation message for diary entries).
• When returning food nutrition, highlight: calories, fat, carbs, protein, and serving size.

Guardrails#

• Never fabricate food IDs, serving IDs, entry IDs, or nutritional values. Always look them up first.
• Before creating or deleting diary entries, confirm the action with the user.
• Before deleting saved meals or favorites, confirm with the user.
• Prefer read-only operations (search, get) unless the user explicitly asks to create, edit, or delete.
• Profile-scoped operations (diary, favorites, exercises, weight) require a profile to be created first via profile_create.

Failure handling#

• If the script exits non-zero, show the error message to the user.
• Common errors:
  • Code 2: "Requires authenticated session" — delegated credentials are missing.
  • Code 101–108: Parameter error — a required parameter is missing or invalid.
  • Code 201–207: Application error — contact FatSecret support.
• If a search returns no results, tell the user and suggest refining the query.
• If a date is required but not provided, ask the user which date they mean.

External endpoints#

EndpointMethodData senthttps://platform.fatsecret.com/rest/v2/server.apiPOSTOAuth 2.0 bearer-token authorized requests: method name, search terms, food/recipe/entry IDs, dates, serving sizes, weight values. No raw user content beyond search queries.https://oauth.fatsecret.com/connect/tokenPOSTOAuth 2.0 client credentials grant (client_id, client_secret) to obtain access tokens.

No other endpoints are contacted. All network calls are made by the pyfatsecret Python package via the requests library.

Security and privacy#

• What leaves the machine: Search queries, food/recipe/entry IDs, serving sizes, weight values, and OAuth 2.0 credentials are sent to platform.fatsecret.com and oauth.fatsecret.com over HTTPS.
• What stays local: The script reads environment variables for credentials and prints JSON to stdout. No data is written to disk. No data is sent to any service other than FatSecret.
• Credentials: Client ID/secret are read from environment variables only. They are never logged or printed.
• Shell safety: The script is pure Python using the requests library. There is no shell expansion or interpolation of user input.

Model invocation note#

This skill may be invoked autonomously by the agent when it determines the user's request matches the skill's capabilities (food search, nutrition lookup, diary management, etc.). This is standard OpenClaw behavior. To disable autonomous invocation, configure the skill as manual-only in your OpenClaw settings.

Trust statement#

By using this skill, food-related queries and diary data are sent to the FatSecret API ( platform.fatsecret.com) over HTTPS. Only install this skill if you trust the FatSecret platform with your nutritional and health data. Review the FatSecret API Terms of Use before use.