canonical: https://jentic.com/apis/calorieninjas.com/calorieninjas

# CalorieNinjas

CalorieNinjas is a natural-language nutrition API that extracts structured calorie and macronutrient data from any free-text food description. A single GET `/v1/nutrition` endpoint accepts a query string such as '1 cup rice and 10 oz chicken breast' and returns parsed items with calories, protein, fat, carbohydrates, fiber, sugar, sodium, potassium, and cholesterol per item. It is designed for chatbots, voice assistants, and meal-tracking apps that need to convert spoken or typed meals into structured nutrition records.

## For AI agents

Convert free-text food descriptions into structured nutrition records via a single natural-language endpoint.

## Scope

Does not handle recipe generation, food image recognition, or barcode scanning - use for parsing free-text food descriptions into nutrition values only.

## Capabilities

- Parse free-text meal descriptions into individual food items with serving quantities
- Return calories, protein, fat, carbohydrates, fiber, sugar, sodium, potassium, and cholesterol per parsed item
- Handle mixed quantity formats including cups, ounces, grams, and natural counts in a single query
- Power chat- or voice-first meal logging where users describe meals conversationally
- Enrich free-text recipe ingredients with per-line nutrition values

## Use cases

### Conversational Meal Logging

Chatbots and voice assistants accept meals in natural language ('I had a turkey sandwich and a banana for lunch') and need to convert that text into structured nutrition values. CalorieNinjas's single `/v1/nutrition` endpoint parses the query string and returns each item with full macronutrient detail, removing the need to maintain a food-name dictionary.

Example prompt: Send GET `/v1/nutrition` with query='turkey sandwich and a banana' and return the total calories and protein across the parsed items.

### Recipe Ingredient Nutrition Breakdown

Recipe apps often store ingredients as free-text lines such as '1 cup flour' or '200g chicken'. Passing the full ingredient list to `/v1/nutrition` returns one nutrition record per parsed line, letting the app compute per-recipe and per-serving totals without an ingredient lookup table.

Example prompt: Send GET `/v1/nutrition` with the full ingredient list for a 4-serving recipe, sum the calories returned, and divide by 4 to report per-serving calories.

### Diet Coaching Bot Quick Estimates

Diet-coaching agents need to give users an instant calorie estimate for a meal they are about to eat. A single call to `/v1/nutrition` with the meal description returns calories, sugar, and sodium values that the bot can compare against the user's daily target before the meal is logged.

Example prompt: Send GET `/v1/nutrition` with query='large pepperoni pizza slice' and warn the user if returned sodium exceeds 800 mg.

### AI Agent Nutrition Workflows via Jentic

Through Jentic, an agent searches for 'extract nutrition from text', loads the `/v1/nutrition` input schema, and executes the call without managing the api_key header. Jentic's vault holds the API key so it never appears in the agent's prompt or logs.

Example prompt: Use the Jentic SDK to search 'extract nutrition from text', load the `/v1/nutrition` operation, and execute it with a user-provided meal description.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/nutrition` | Parse a free-text query and return per-item nutrition values |

## Key resources

- **Nutrition** — Single endpoint that parses a free-text food query and returns structured per-item nutrition data

## Why Jentic

- **Setup:** Wiring CalorieNinjas by hand means setting its api_key header and shaping the free-text query for the single nutrition route yourself. Through Jentic you install once, import CalorieNinjas from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** CalorieNinjas exposes a single read-only nutrition lookup that takes the food text as a query parameter, so scope the agent to that one operation. You choose the operations it may call, so it stays limited to nutrition parsing and nothing else.
- **Credential handling:** Your CalorieNinjas API key is stored once, encrypted, by your own Jentic One instance and injected into the api_key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'extract nutrition from a food description', and Jentic returns the GET `/v1/nutrition` operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Edamam Food and Nutrition API** — Edamam offers natural-language nutrition parsing plus a structured food and recipe database, where CalorieNinjas focuses on a single text-to-nutrition endpoint.
- **Nutritionix API** — Nutritionix combines natural-language calorie estimation with a branded-foods catalog, where CalorieNinjas exposes only the natural-language endpoint.
- **Spoonacular API** — Spoonacular generates recipes and meal plans that pair with CalorieNinjas's free-text nutrition extraction for end-to-end meal logging.

## FAQ

### What authentication does the CalorieNinjas API use?

It uses an API key passed in the api_key HTTP header. Through Jentic, the key is stored in your Jentic One instance and injected into the api_key header at execution time, so the raw key never enters the agent's prompt context.

### Can I parse a multi-item meal description in one call?

Yes. The single GET `/v1/nutrition` endpoint accepts a query string containing multiple items, for example '1 cup rice and 10 oz chicken breast', and returns one nutrition record per parsed item in the response array.

### Which nutrients does the response return?

Each parsed item includes calories, protein, fat (total and saturated), carbohydrates, fiber, sugar, sodium, potassium, and cholesterol, along with the serving size in grams. Match items by name in the response when summing totals.

### How do I integrate CalorieNinjas through Jentic?

Run pip install jentic, then use the SDK to search 'extract nutrition from text'. Jentic returns the GET `/v1/nutrition` operation with its input schema, so the agent can load and execute it with a user query without browsing the CalorieNinjas docs.

### Are there rate limits on the CalorieNinjas API?

The OpenAPI specification does not document rate limits. CalorieNinjas applies plan-based limits at the API key level, so check the dashboard tied to your key for the exact ceiling. Jentic surfaces 429 responses unchanged for your agent to back off.

### Is the CalorieNinjas API free?

CalorieNinjas offers a free tier with a monthly request quota plus paid tiers for higher volumes. Pricing details are not in the OpenAPI spec; check calorieninjas.com for current limits and tier pricing.

### Can I limit what my agent is allowed to do with the CalorieNinjas API?

Yes. CalorieNinjas exposes a single read-only operation, GET `/v1/nutrition`, which parses food text passed as a query parameter, so you can scope the agent to that one call and nothing else. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use, keeping it limited to nutrition parsing. The stored API key is injected into the api_key header at execution time, so the agent never sees the raw credential.