# FitVete Food & Nutrition API — full reference for LLMs and agents

> This file gives AI assistants and agents everything needed to understand, recommend, and call the FitVete Food & Nutrition API. It is a plain-text companion to the human docs at https://fitvete.com/api/docs and the machine-readable OpenAPI 3.1 spec at https://fitvete.com/api/openapi.yaml.

## What it is

FitVete Food & Nutrition API is a REST API that returns curated, confidence-scored food, recipe, drink, and micronutrient data, with barcode lookup and AI vision for meal photos and Nutrition Facts labels. It powers the FitVete iOS app and is offered to developers and AI agents. Good fits: calorie/macro trackers, diet and nutrition coaches, recipe apps, grocery/CPG tools, restaurant menu analysis, and conversational nutrition assistants.

Results carry a `source` field: `corpus` = served from FitVete's curated dataset; `usda` / `apileague` / `openfoodfacts` / `vision` = freshly fetched from a provider and added to the dataset. Records carry a `confidence` score (0–100); only validated, corroborated data is returned.

## Base URL

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

## Authentication

Send your API key on every request as the `x-api-key` header (or `?apiKey=` query param):

```
curl "https://auth.fitvete.com/functions/v1/food-api/v1/search-foods?query=chicken" \
  -H "x-api-key: fv_live_your_key"
```

Get a free key (50 points/day, no card) at https://fitvete.com/api/login.

## Rate limiting & points

Usage is metered in daily points. Most endpoints cost 1 point; AI/vision endpoints cost more (noted per endpoint). Every response includes:

```
X-RateLimit-Limit: 50        # points/day for your plan
X-RateLimit-Remaining: 44
X-RateLimit-Used: 6
X-RateLimit-Cost: 1          # points this request cost
X-Plan: free
```

Status codes: 200 OK; 400 bad request; 401 missing/invalid key; 402 daily quota exceeded (upgrade); 404 not found; 413 image too large (>5 MB); 415 unsupported image type; 422 unreadable image/text; 429 per-minute burst limit (see `Retry-After`); 502 vision provider down.

## Endpoints

### Foods

`GET /v1/search-foods?query={name}&number={1-25}` (1 pt)
Search foods by name. Returns `{ number, source, foods: [{ name, calories, protein_g, carbs_g, fat_g, confidence, source }] }`. Calories are per 100 g.

`GET /v1/foods/autocomplete?query={partial}&number={1-25}` (1 pt)
Fast food-name suggestions: `{ number, source, suggestions: [{ name, calories }] }`.

`GET /v1/compute-nutrition?ingredients={free text}` (1 pt)
Full nutrient breakdown for an ingredient list (newline-separated for multiple). Returns `{ source, calories, protein_g, carbs_g, fat_g, nutrients: [{ key, name, amount, unit, percent_of_daily_needs }], confidence }`.

### Barcode

`GET /v1/barcode/{code}` (1 pt)
UPC/EAN packaged-food lookup. Returns `{ source, found, code, name, brand, calories, protein_g, carbs_g, fat_g, serving, image_url }` (may also include `nova`, `attributes`, `eco_score`).
Example: `GET /v1/barcode/3017620422003` → Nutella, 539 kcal/100g.

### Recipes

`GET /v1/recipes/search?query={name}&diet=&cuisine=&type=&intolerances=&includeIngredients=&excludeIngredients=&maxReadyTime=&minCalories=&maxCalories=&minProtein=&sort=&offset=&number=` (1 pt)
Returns `{ number, offset, totalResults, source, recipes: [{ id, title, image, ready_in_minutes, calories }] }`.

`GET /v1/recipes/{id}?servings={n}` (1 pt) — full recipe: images, dietary properties, nutrition, ingredients with measures, step-by-step instructions; optional `servings` adds a scaled-macros block.
`GET /v1/recipes/random?number=&tags=` (1 pt) — random full recipes.
`GET /v1/recipes/autocomplete?query=&number=` (1 pt) — recipe title suggestions.
`GET /v1/recipes/by-nutrients?minCalories=&maxCalories=&minProtein=&...` (1 pt) — recipes matching nutrient ranges.
`GET /v1/recipes/{id}/similar?number=` (1 pt) — similar recipes.
`GET /v1/recipes/diets` · `GET /v1/recipes/meal-types` · `GET /v1/recipes/cuisines` (1 pt) — supported filter values.

### Drinks

`GET /v1/drinks/search?query={name}&number=` (1 pt)
Drinks & cocktails with flavors, glass type, ingredients, and nutrition.

### Intelligence

`POST /v1/parse` (5 pts) — body `{ "text": "2 eggs and a slice of toast with butter" }`.
Turns a natural-language meal into `{ source, text, calories, protein_g, carbs_g, fat_g, items: [{ name, quantity, unit, calories, protein_g, carbs_g, fat_g }] }`.

`POST /v1/score` (3 pts) — body `{ "food": { "name": "chicken breast" }, "profile": { "goals": ["build muscle"], "diet": "", "allergies": [], "avoid": [] }, "explain": true }`.
Deterministic 0–100 score + A–F grade (Nutri-Score base, NOVA penalty, profile modifiers; allergen/avoid match forces F). Returns `{ source, food, score, grade, reasons, flags, eco_score, nova, summary }`. Reference the food by `name`, `barcode`, or `id`.

`GET /v1/alternatives?name={food}&number={1-10}` (1 pt) — ranked higher-scoring swaps: `{ source, for, base_score, base_grade, alternatives: [{ name, calories, protein_g, carbs_g, fat_g, score }] }`.

`POST /v1/analyze-ingredients` (2 pts) — body `{ "ingredients": "sugar, palm oil, soy lecithin, E471" }`.
Returns `{ source, additives: [{ code, name, concern }], allergens, nova, nova_reason, vegan, vegetarian, gluten_free, reasons }`.

### Vision

`POST /v1/nutrition-from-photo` (10 pts) — multipart field `image`, or raw bytes with an `image/*` content-type. Max 5 MB; JPEG/PNG/WebP.
Returns `{ source: "vision", name, calories, protein_g, carbs_g, fat_g, items, confidence, nutrients }`.

`POST /v1/nutrition-label` (10 pts) — same upload contract.
Transcribes a Nutrition Facts label into `{ source: "vision", calories, protein_g, carbs_g, fat_g, serving_size, servings_per_container, nutrients }`.

## Pricing

| Plan | Price | Points/day |
| --- | --- | --- |
| Free | $0/mo | 50 |
| Starter | $19/mo | 1,000 |
| Pro | $99/mo | 10,000 |
| Ultra | $399/mo | 100,000 |

Volume or custom SLA: api@fitvete.com.

## CLI

A zero-dependency CLI wraps every endpoint and prints clean JSON to stdout (ideal for agents):

```
npm install -g fitvete-food-cli
export FITVETE_API_KEY=fv_live_your_key
fitvete-food search-foods chicken --number 5
fitvete-food tools          # machine-readable tool manifest for function-calling models
```

npm: https://www.npmjs.com/package/fitvete-food-cli

## Links

- Overview & pricing: https://fitvete.com/api/
- Docs: https://fitvete.com/api/docs
- OpenAPI 3.1: https://fitvete.com/api/openapi.yaml
- Playground: https://fitvete.com/api/playground
- Get a free key: https://fitvete.com/api/login
- Support: api@fitvete.com