API documentation

The FitVete Food & Nutrition API is a simple REST + JSON service. Every request is authenticated with an API key and metered by daily points. Pick your language once — the selector below switches every code sample on the page.

Introduction

Base URL:

https://auth.fitvete.com/functions/v1/food-api

Most endpoints are GET; the image endpoints (photo & label) are POST with an image body. All return JSON.
Authentication is the x-api-key request header (or ?apiKey= query param).
Responses include a source field: corpus (served from our curated dataset), or usda/apileague when freshly fetched and added to the dataset.

Quick start

Make your first call in under a minute:

1. Create a free account and copy your key (fv_live_…) from the dashboard.

2. Put it in your environment, then call any endpoint:

3. Check your remaining quota in the response headers (see Rate limits). That's it — no SDK required, though one is available (see OpenAPI & SDKs).

Authentication

Create a free account and copy your key from the dashboard. Keys look like fv_live_…. Send it on every request:

Keep your key secret — treat it like a password. You can create up to 5 keys and delete any of them at any time from the dashboard. Deleting a key takes effect immediately.

Rate limits & points

Each request spends points — most cost 1, image (vision) endpoints cost 10 (see the table below). Your daily point budget depends on your plan, and there is also a per-minute burst ceiling to keep the API fast for everyone.

Plan	Points / day	Burst / minute
Free	50	60
Starter	1,000	120
Pro	10,000	300
Ultra	100,000	600

Every response carries your current usage in headers:

X-RateLimit-Limit: 50 X-RateLimit-Remaining: 44 X-RateLimit-Used: 6 X-RateLimit-Cost: 1 X-Plan: free

Most endpoints cost 1 point. Vision endpoints cost more because they call image providers:

Endpoint	Points
`/v1/search-foods`, `/v1/compute-nutrition`, recipes, drinks, barcode, autocomplete, alternatives	1
`/v1/analyze-ingredients`	2
`/v1/score`	3
`/v1/parse`	5
`/v1/nutrition-from-photo`	10
`/v1/nutrition-label`	10

Data & concepts

A few fields appear across responses and are worth understanding:

Field	What it means
`source`	Where the answer came from: `corpus` (our curated, owned dataset — instant and free of upstream cost), or `usda` / `apileague` / `openfoodfacts` / `vision` when freshly fetched on a miss and then added to the corpus.
`confidence`	0–100 trust score. It rises as independent lookups corroborate a value, so popular foods get more accurate over time. Only validated, corroborated rows are exposed.
Macro units	Food results are per 100 g. `calories` are kcal; `protein_g` / `carbs_g` / `fat_g` are grams. Each micronutrient in `nutrients[]` carries its own `amount` + `unit`.

The dataset is self-improving: any query that isn't already stored is fetched from a provider, cleaned, and saved — so repeat lookups are served from our corpus, get faster, and improve in accuracy with every corroboration.

Errors

Standard HTTP status codes. Error bodies are { "status": "failure", "code": <int>, "message": "…" }.

Status	Meaning
`200`	OK
`400`	Missing or invalid parameter
`401`	Missing, invalid, or deleted API key
`402`	Daily point limit reached — upgrade your plan
`404`	Not found (e.g. unknown recipe id)
`413`	Image upload exceeds the 5 MB limit
`415`	Unsupported image type — use JPEG, PNG, or WebP
`422`	Image is valid, but nutrition could not be read clearly
`429`	Per-minute burst limit hit — retry after `Retry-After` seconds
`502`	Vision provider temporarily unavailable — retry
`503`	Authorization temporarily unavailable — retry

Search foods

GET/v1/search-foods

Search the food database by name. Returns calories, macros, and a confidence score per match.

Param	Type	Required	Description
`query`	string	yes	Food name, e.g. `chicken`.
`number`	int	no	Max results, 1–25 (default 10).

Example response

{ "number": 1, "source": "corpus", "foods": [ { "name": "chicken breast", "calories": 120, "protein_g": 22, "carbs_g": 0, "fat_g": 3, "confidence": 100, "source": "food" } ] }

Compute nutrition

GET/v1/compute-nutrition

Full nutrient breakdown for a free-text ingredient list — macros plus 25+ vitamins & minerals, properties, and caloric breakdown.

Param	Type	Required	Description
`ingredients`	string	yes	One or more ingredients, e.g. `1 cup rice`. Separate multiple lines with newlines.

Example response

{ "source": "apileague", "calories": 206, "protein_g": 4, "carbs_g": 45, "fat_g": 0, "nutrients": [ { "key": "fiber", "name": "Fiber", "amount": 0.6, "unit": "g" } ], "confidence": 100 }

Search recipes

GET/v1/recipes/search

Search by name and/or filters. A plain name query is served from our corpus first; filtered or paged searches run upstream. Returns id, title, image, ready time, and calories per result. Pass query or at least one filter.

Param	Type	Description
`query`	string	Name or keywords (optional if a filter is given).
`diet`	string	e.g. `vegetarian`, `vegan`, `ketogenic`, `paleo`. See diets.
`cuisine`	string	e.g. `italian`, `mexican`, `asian`. See cuisines.
`type`	string	Meal type, e.g. `breakfast`, `dessert`, `main course` (alias `mealType`). See meal types.
`intolerances`	string	Comma-separated, e.g. `gluten,dairy`.
`includeIngredients`	string	Comma-separated must-include ingredients.
`excludeIngredients`	string	Comma-separated must-exclude ingredients.
`maxReadyTime`	int	Max minutes to prepare.
`minCalories` / `maxCalories`	int	Calorie range.
`minProtein`	int	Protein floor (g).
`sort`	string	e.g. `popularity`, `calories`, `time`, `protein`.
`offset`	int	Pagination offset (0–900).
`number`	int	Max results, 1–25 (default 10).

Example response

{ "number": 1, "offset": 0, "totalResults": 42, "source": "corpus", "recipes": [ { "id": 715538, "title": "Pasta With Chicken and Mushrooms", "image": "https://…jpg", "ready_in_minutes": 35, "calories": 463 } ] }

Random recipes

GET/v1/recipes/random

Return random full recipes (great for "surprise me" / discovery). Harvested into the corpus.

Param	Type	Description
`number`	int	How many, 1–25 (default 5).
`tags`	string	Comma-separated diet/meal tags, e.g. `vegetarian,dessert`.

Recipe autocomplete

GET/v1/recipes/autocomplete

Title suggestions for a partial query — ideal for search-as-you-type.

Param	Type	Required	Description
`query`	string	yes	Partial recipe name, e.g. `choc`.
`number`	int	no	Max suggestions, 1–25 (default 10).

Recipes by nutrients

GET/v1/recipes/by-nutrients

Find recipes that fit calorie/protein/carb/fat ranges — perfect for macro-target meal planning. At least one range is required.

Param	Type	Description
`minCalories` / `maxCalories`	int	Calorie range.
`minProtein` / `maxProtein`	int	Protein range (g).
`minCarbs` / `maxCarbs`	int	Carb range (g).
`minFat` / `maxFat`	int	Fat range (g).
`number`	int	Max results, 1–25 (default 10).

Similar recipes

GET/v1/recipes/{id}/similar

Recipes similar to a given id — for "you might also like" recommendations.

Param	Type	Required	Description
`id`	int	yes	Recipe id (path segment).
`number`	int	no	Max results, 1–25 (default 5).

Diets, cuisines & meal types

Reference lists of the values accepted by the search filters (no upstream call):

GET/v1/recipes/diets — supported diet values.
GET/v1/recipes/cuisines — supported cuisine values.
GET/v1/recipes/meal-types — supported type values.

Get recipe

GET/v1/recipes/{id}

Full recipe detail: images, dietary properties, nutrition, ingredients with measures, and step-by-step instructions.

Param	Type	Required	Description
`id`	int	yes	Recipe id (path segment), e.g. `715538`.
`servings`	int	no	Adds a `serving_scale` block with macros scaled to this many servings.

Search drinks

GET/v1/drinks/search

Search drinks and cocktails — flavors, glass type, ingredients, and nutrition.

Param	Type	Required	Description
`query`	string	yes	Drink name, e.g. `margarita`.
`number`	int	no	Max results, 1–25 (default 10).

Barcode lookup

GET/v1/barcode/{code}

Look up a packaged food by UPC/EAN barcode. Results are harvested into the owned corpus so repeat lookups can serve from FitVete data.

Param	Type	Required	Description
`code`	string	yes	Numeric barcode path segment. Non-digits are ignored.

Photo nutrition

POST/v1/nutrition-from-photo

Estimate meal calories, macros, visible items, and nutrients from a JPEG, PNG, or WebP meal photo. Send raw image bytes with an image/* content type, or multipart form field image.

Max 5 MBJPEG / PNG / WebP10 points

Nutrition label

POST/v1/nutrition-label

Parse a Nutrition Facts label photo into per-serving calories, macros, serving information, and printed nutrients. Send raw image bytes with an image/* content type, or multipart form field image.

Max 5 MBJPEG / PNG / WebP10 points

Nutrition intelligence

Beyond raw data, these endpoints add the judgment layer: a personalized health score, ingredient/additive analysis, natural-language meal parsing, and healthier swaps. The scoring engine is deterministic and explainable — a pure function of nutrients, processing (NOVA), and your user's profile — so every grade is auditable, not a black-box number. AI is used only for natural-language summaries and free-text parsing, and always degrades to the rules-based result on failure.

Scoring rubric: a Nutri-Score-derived base (0–100) penalizes energy, saturated fat, sugar, and sodium and rewards fiber and protein; an ultra-processing (NOVA 4/3) penalty is subtracted; then profile modifiers adjust for the user's goals and diet. An allergen or avoid-list match forces grade F. Sustainability/eco data is community-sourced (Open Food Facts) with variable coverage.

Personalized score

POST/v1/score 3 points

Score a food 0–100 with an A–F grade and human-readable reasons, tuned to the user's profile. Reference the food by name, barcode, or id.

Body field	Type	Description
`food.name` / `food.barcode` / `food.id`	string	One is required. Barcode pulls richer data (additives, NOVA, eco).
`profile.goals`	string[]	e.g. `["build muscle","low sugar"]` — adjusts the score.
`profile.diet`	string	e.g. `vegan`, `keto` — penalizes/flags violations.
`profile.allergies`	string[]	A match forces grade F + flag.
`profile.avoid`	string[]	Ingredients to avoid; a match forces grade F.
`explain`	bool	Add a one-line natural-language `summary`.

Example response

{ "source": "corpus", "food": "chicken breast", "score": 96, "grade": "A", "reasons": [ "High protein (22 g/100g)", "Bonus: high protein for your muscle goal" ], "flags": [], "eco_score": null, "nova": null }

Analyze ingredients

POST/v1/analyze-ingredients 2 points

Detect additives/E-numbers (with concern level), allergens, the NOVA ultra-processing level (1–4), and vegan/vegetarian/gluten-free flags from an ingredient list.

Body field	Type	Required	Description
`ingredients`	string	yes	Comma-separated ingredient list (≤ 4000 chars).

Example response

{ "nova": 4, "vegan": false, "vegetarian": true, "gluten_free": true, "additives": [ { "code": "E471", "name": "Mono- and Diglycerides", "concern": "low" } ], "allergens": [ "milk", "tree nut", "soy" ] }

Parse meal (NLP)

POST/v1/parse 5 points

Turn a free-text meal into structured items with quantities and per-item + total nutrition.

Body field	Type	Required	Description
`text`	string	yes	Natural-language meal, e.g. `"2 eggs and a slice of toast"` (≤ 1000 chars).

Example response

{ "source": "vision", "calories": 286, "protein_g": 15, "carbs_g": 18, "fat_g": 17, "items": [ { "name": "Scrambled eggs", "quantity": 2, "unit": "large", "calories": 182 } ] }

Healthier swaps

GET/v1/alternatives 1 point

Given a food, return higher-scoring alternatives from the catalog, ranked best-first.

Param	Type	Description
`name` / `barcode` / `id`	string	One is required.
`number`	int	Max swaps, 1–10 (default 5).

Food autocomplete

GET/v1/foods/autocomplete 1 point

Fast food-name typeahead from the corpus (upstream fallback on a miss).

Param	Type	Required	Description
`query`	string	yes	Partial food name.
`number`	int	no	Max suggestions, 1–25 (default 10).

Command-line interface (CLI)

The fitvete-food CLI wraps every endpoint and prints clean JSON to stdout — ideal for scripts, pipelines, and AI agents. Install it from npm: fitvete-food-cli.

# install from npm (Node 18+) npm install -g fitvete-food-cli # one-time: set your key export FITVETE_API_KEY=fv_live_your_key # search foods fitvete-food search-foods chicken --number 5 # compute nutrition for an ingredient list fitvete-food compute "1 cup rice" "2 eggs" # recipes & drinks fitvete-food recipes pasta fitvete-food recipe 715538 fitvete-food drinks margarita fitvete-food barcode 012345678905 fitvete-food photo ./meal.jpg fitvete-food label ./nutrition-label.jpg # human-readable table instead of JSON fitvete-food search-foods banana --pretty

--key <key> — override FITVETE_API_KEY.
--number <n> — result count for search commands.
photo and label accept local JPEG, PNG, or WebP files up to 5 MB.
--pretty — formatted table for humans (default output is raw JSON).
Exit codes: 0 ok, 1 request error, 2 usage error, 3 auth/limit.

AI agents

The CLI is built to be driven by autonomous agents. It emits a machine-readable tool manifest you can hand straight to a function-calling model, and every command returns parseable JSON with a non-zero exit code on failure.

# print a JSON tool manifest (function-calling schema for every command) fitvete-food tools

A typical agent loop: read fitvete-food tools once to learn the available functions, then call commands and parse stdout. Because output is pure JSON (no prompts, no spinners), it pipes cleanly into jq or any parser:

fitvete-food search-foods salmon | jq '.foods[0].protein_g'

Working in Claude, Cursor, or another MCP client? The CLI doubles as the data layer for an MCP server — wrap the same commands as MCP tools, or run the CLI directly via a shell tool. See the CLI README in the repo (cli/) for an MCP snippet.

OpenAPI & SDKs

The full API is described by an OpenAPI 3.1 specification. Use it to explore endpoints, import into a client, or generate a typed SDK in your language:

# Import into Postman or Insomnia # File → Import → URL → https://fitvete.com/api/openapi.yaml # Generate a client SDK (Python, TypeScript, Go, Java, Swift, …) npx @openapitools/openapi-generator-cli generate \ -i https://fitvete.com/api/openapi.yaml \ -g python -o ./fitvete-sdk # Or try requests live with the spec curl https://fitvete.com/api/openapi.yaml

Prefer not to generate one? The CLI works everywhere with zero setup, and the per-language samples above copy-paste into any project.

Best practices

Budget your points. Most calls cost 1 point; image (vision) calls cost 10. Read X-RateLimit-Remaining and back off before you hit zero.
Handle 402 and 429. A 402 means your daily budget is spent (upgrade or wait for reset); a 429 means you exceeded the per-minute burst — wait the Retry-After seconds and retry. Use exponential backoff for transient 502/503.
Cache on your side. Food facts are stable — cache results by query/barcode to spend fewer points. (We already serve repeats from our corpus, but client caching saves a round trip.)
Send clear images. For photo/label endpoints, use a well-lit, straight-on shot under 5 MB (JPEG/PNG/WebP). A blurry label returns 422 rather than guessed numbers.
Keep keys server-side. Never ship a key in a public web/mobile client; proxy through your backend. Rotate by creating a new key and deleting the old one (takes effect immediately).

FAQ

Is there a free tier? Yes — 50 points/day, no card required. Upgrade anytime for more.

How do points reset? Daily. Your budget refreshes each calendar day (UTC).

What does source: "corpus" mean? The answer came from our owned, curated dataset. Other values mean it was just fetched from a provider and added to the dataset for next time. See Data & concepts.

Why did a food return slightly different numbers than another API? Values are per 100 g from curated, corroborated sources with a confidence score; they converge toward accuracy as more lookups agree.

Can I use this from an AI agent? Yes — the CLI emits a function-calling manifest (fitvete-food tools) and pure-JSON output. See AI agents.

Do you have higher limits / an SLA? Yes — see plans or email api@fitvete.com for volume/custom pricing.

Changelog

Version	Changes
`1.4`	Nutrition intelligence: personalized `/v1/score` (Nutri-Score+NOVA, profile-aware, allergen hard-fail), `/v1/analyze-ingredients`, `/v1/parse` (NLP), `/v1/alternatives`, `/v1/foods/autocomplete`; `attributes` badges + `eco_score` on food/barcode responses.
`1.3`	Expanded recipe surface: filtered search (diet, cuisine, intolerances, ingredients, time, calorie/protein), random, autocomplete, similar, by-nutrients, diet/cuisine/meal-type reference lists, and a servings scaler on recipe detail.
`1.2`	Added barcode lookup, photo nutrition, and Nutrition Facts label endpoints; per-endpoint point costs; `X-RateLimit-Cost` header.
`1.1`	Self-growing corpus: on a miss, results are fetched upstream, returned, and saved. Added `source` field.
`1.0`	Initial release: foods, compute-nutrition, recipes, drinks; API keys, tiered daily points, burst limits.

Get your free API key Download OpenAPI spec Open dashboard