basalfit API

GET /api/v1/recipes

Search recipes in plain language or by filters

One result per dish (family), best-matching version first. Filters combine with `q`, which the Ask bar parser reads ("vegan, no peanuts, under 600 kcal").

Responses: 200 Matching recipes, with a USDA citation

Try it: curl "https://basalfit.com/api/v1/recipes?q=vegan%2C+no+peanuts%2C+under+600+kcal&diets=vegetarian&exclude=peanuts&have=spinach&max_kcal=700&min_protein_g=10&max_minutes=60&cuisine=Indian&limit=10"

GET /api/v1/pantry

What can I make? Recipes from what you have

Reads `have` like the Ask bar ("I have chicken, rice and spinach"). Amounts are weighed with USDA portions, and a recipe needing more than you have lists it as short; an ingredient without an amount counts as enough. Staples (salt, oil, water) count as on hand. Fewest missing ingredients first, then the largest share on hand; one result per dish.

Responses: 200 Recognized ingredients (with grams when an amount was given), words not recognized, staples, and recipes with what each is missing or short of

Try it: curl "https://basalfit.com/api/v1/pantry?have=2+cups+rice%2C+500+g+chicken%2C+spinach&max_missing=1&limit=10"

GET /api/v1/recipes/{slug}

Get a recipe

Ingredients with their USDA sources, steps, per-serving label nutrition, diets, and every nutrient per serving.

Responses: 200 The recipe · 404 Not found

Try it: curl "https://basalfit.com/api/v1/recipes/garlic-chicken-spinach-rice-bowl"

GET /api/v1/foods

Search USDA foods by name

Common forms first; a misspelled word is corrected when nothing matches, and `corrected` says what was searched.

Responses: 200 Matching foods with per-100 g macros

Try it: curl "https://basalfit.com/api/v1/foods?q=greek+yogurt&limit=5"

GET /api/v1/foods/{id}

Get one food: every nutrient, portions and ranks

Responses: 200 The food · 404 Not found

Try it: curl "https://basalfit.com/api/v1/foods/170894"

GET /api/v1/foods/barcode/{code}

Get a packaged food by its barcode

UPC-A, UPC-E, EAN-8, EAN-13 or GTIN-14, with or without spaces. The label's nutrients per 100 g and its serving, from USDA Branded Foods (with ingredients), then products basalfit members added and a moderator approved, then Open Food Facts (ODbL; records whose numbers don't add up are left out). `source` names which, with `citation` for USDA and Open Food Facts. 400 when the code isn't a valid barcode; 404 when no source has it.

Responses: 200 The product · 400 Not a valid barcode · 404 Not in USDA's list

Try it: curl "https://basalfit.com/api/v1/foods/barcode/016000275287"

GET /api/v1/foods/compare

Compare two foods, every nutrient per 100 g

Responses: 200 Side by side, with which has more · 404 A food wasn't found

Try it: curl "https://basalfit.com/api/v1/foods/compare?a=170894&b=171265"

GET /api/v1/ingredients/names.json

Ingredient names in other languages and scripts

A map from ingredient id to its names, from Wikidata, for reading recipes not written in English.

Responses: 200 Names by ingredient id

Try it: curl "https://basalfit.com/api/v1/ingredients/names.json"

POST /api/v1/nutrition

Nutrition for any ingredient list

FDA-rounded label values, % Daily Value and diets, from USDA data.

Responses: 200 Per-serving nutrition · 400 Invalid lines · 422 Unknown ingredient

POST /api/v1/recipes

Submit a recipe · needs a basalfit.com session

Saved for review (trusted contributors publish immediately). Ingredients are by id, or by name when basalfit doesn't list them yet. A near-copy of an existing recipe returns 409 unless `confirm` is "duplicate". 10 a day per person.

Responses: 201 Saved: its slug and how it relates to existing dishes · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 409 Looks like an existing recipe · 422 Unknown ingredient or unconvertible unit · 429 Daily limit reached

PUT /api/v1/recipes/{slug}

Edit a recipe (its author or a moderator) · needs a basalfit.com session

Same body as a submission. A moderator's edit keeps the status; a trusted author's edit of a published recipe stays published; other edits go back to review.

Responses: 200 Saved, with the recipe's new status · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 404 Not found

POST /api/v1/products

Add a packaged food from its Nutrition Facts panel · needs a basalfit.com session

For barcodes USDA doesn't list. Values are per serving, as on the label; they're checked (parts within totals, calories near protein, carbohydrate and fat) and kept per 100 g. Pending until a moderator approves; the response includes the product, shaped like a food, so the submitter can log it now. 20 a day per person.

Responses: 201 Added for review · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 409 USDA lists it, or it was already added · 429 Daily limit reached

GET /api/v1/recipes/{slug}/editable

Get a recipe as its author or a moderator edits it · needs a basalfit.com session

Responses: 200 Every line by ingredient id or unlisted name · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 404 Not found

POST /api/v1/recipes/{slug}/reports

Report a problem with a recipe · needs a basalfit.com session

One report per person per recipe; three open reports from different people hide it until a moderator reviews it.

Responses: 201 Recorded; `hidden` says whether this report hid the recipe · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 404 Not found

POST /api/v1/moderation/products/{gtin}

Approve or reject an added product (moderators only) · needs a basalfit.com session

Responses: 200 Reviewed · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 404 No pending product with that barcode

GET /api/v1/moderation/queue

What moderators review (moderators only) · needs a basalfit.com session

Responses: 200 Pending, reported and unlisted-line recipes · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com

POST /api/v1/moderation/recipes/{id}

Approve, reject, restore, edit or map a line (moderators only) · needs a basalfit.com session

Responses: 200 Done · 400 Invalid input · 401 Sign in first · 403 Not allowed, or not from basalfit.com · 404 No such recipe or line

GET /api/health

Health of the service and its database and storage

`build` names the build serving, so a deploy can be checked to have gone live.

Responses: 200 Healthy · 503 A dependency is down

Try it: curl "https://basalfit.com/api/health"

GET /mcp

Model Context Protocol server: not used with GET

Remote MCP over Streamable HTTP, no authentication. Tools: search_recipes, get_recipe, search_foods, get_food, nutrition_for. See https://basalfit.com/ai.

Responses: 405 Use POST: the server is stateless, with no event stream

POST /mcp

MCP JSON-RPC requests

Responses: 200 JSON-RPC response · 202 Notification accepted