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

# BigOven API

Jentic publishes the only available OpenAPI specification for BigOven API, keeping it validated and agent-ready. BigOven is a recipe, meal-planning, and grocery-list service with a catalog of hundreds of thousands of recipes searchable by keyword, ingredient, or random pick. The API exposes recipe lookup, photos, reviews, autocomplete, related-recipe suggestions, and a personal grocery list that can be appended to from a recipe in one call. Authentication uses an X-BigOven-API-Key header for read access and HTTP Basic for user-scoped write operations like grocery list updates and reviews.

## For AI agents

Search BigOven recipes, fetch a recipe with photos and reviews, and add ingredients from a recipe directly to a user's grocery list.

## Scope

Does not handle nutrition analysis, restaurant reservations, or food delivery - use for recipe search and BigOven grocery list operations only.

## Capabilities

- Search the BigOven recipe catalog by keyword, cuisine, or course via /recipes
- Retrieve a full recipe with ingredients and directions through `/recipe/{recipeId}`
- Fetch a random recipe with `/recipe/random` for daily-meal suggestions
- Autocomplete recipe titles as a user types via `/recipes/autocomplete`
- Get recipes related to a specified recipe through `/recipe/{recipeId}/related`
- Add a recipe's ingredients to the authenticated user's grocery list with `/grocerylist/recipe/{recipeId}`
- Group grocery list items by store department using `/grocerylist/departmentalize`

## Use cases

### Recipe Search and Discovery

Cooking apps and meal-planning bots query BigOven's catalog by keyword and dietary filter to surface recipes that match the user's intent. The /recipes endpoint accepts free-text queries and returns paginated results with title, ID, and thumbnail, while `/recipes/autocomplete` powers a fast type-ahead box. `/recipe/random` gives a stress-free 'surprise me' option for users who don't know what they want to cook.

Example prompt: Call /recipes with title_kw='chicken curry' and rpp=10, return titles and recipeIds, then call `/recipe/{recipeId}` for the top match

### Grocery List Automation

Meal-prep apps push the ingredients from a chosen recipe straight into the user's BigOven grocery list, then call `/grocerylist/departmentalize` to bucket them by store aisle. The flow uses `/grocerylist/recipe/{recipeId}` for one-shot population and `/grocerylist/item` for ad-hoc additions, with HTTP Basic auth scoping the writes to the signed-in user. This removes the manual transcription step that kills retention in DIY meal-planning workflows.

Example prompt: Call `/grocerylist/recipe/{recipeId}` for recipe 98765 as the authenticated user, then call `/grocerylist/departmentalize` and return the grouped aisle list

### Related-Recipe Recommendations

Recipe sites and chatbots boost engagement by surfacing related dishes after the user views a recipe - same cuisine, same hero ingredient, or matching course. `/recipe/{recipeId}/related` returns BigOven's curated similarity list without needing the integrator to build their own embedding store. Combined with `/recipe/{recipeId}/photos` and `/recipe/{recipeId}/reviews`, the related list powers a full inline browse experience.

Example prompt: Call `/recipe/{recipeId}/related` with recipeId=12345, return the top 5 related titles and IDs for an inline 'You might also like' panel

### Agent-Driven Meal Planning via Jentic

An AI cooking assistant connected through Jentic answers 'what's for dinner tonight?' by calling `/recipe/random`, then lists ingredients and asks if it should add them to the grocery list. Jentic holds the BigOven API key and the user's Basic auth credentials separately, so the agent can mix read and write operations without ever touching the secrets. The agent only needs to declare the high-level intent.

Example prompt: Search Jentic for 'find a recipe', load BigOven `/recipe/random`, execute, then load `/grocerylist/recipe/{recipeId}` and execute with the returned recipeId

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/recipes` | Search recipes by keyword and filters |
| GET | `/recipe/{recipeId}` | Retrieve a full recipe with ingredients and directions |
| GET | `/recipe/random` | Fetch a random recipe |
| GET | `/recipes/autocomplete` | Autocomplete recipe titles |
| GET | `/recipe/{recipeId}/related` | List recipes related to a given recipe |
| POST | `/grocerylist/recipe/{recipeId}` | Add a recipe's ingredients to the grocery list |
| POST | `/grocerylist/departmentalize` | Group grocery list by store department |
| GET | `/me` | Retrieve the authenticated user profile |

## Key resources

- **Recipes** — Search, retrieve, and explore recipes including photos, reviews, and notes
- **Grocery List** — Append individual items, append a full recipe's ingredients, and group by department
- **User and Collections** — Fetch the signed-in user profile and saved recipe collections

## Why Jentic

- **Setup:** Wiring the BigOven API by hand means sending its X-BigOven-API-Key header plus per-user HTTP Basic credentials on every call and building each recipe and grocery-list path yourself. Through Jentic you install once, import BigOven from the API Directory, store both credentials once, and your agent calls it.
- **Permission scoping:** BigOven puts the recipe id in the URL path (`/recipe/{recipeId}`, `/grocerylist/recipe/{recipeId}`), so a rule can pin your agent to one recipe. You choose the operations it may call, so adding a recipe to a grocery list is not included unless you add it.
- **Credential handling:** Your BigOven API key and per-user Basic credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a recipe' or 'add ingredients to my grocery list', and Jentic returns the matching BigOven operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Spoonacular API** — Recipe search plus full nutritional analysis and meal planning
- **Edamam API** — Recipe search and food database with diet and allergen filtering
- **Food Standards Agency API** — UK food hygiene rating data for restaurants and food businesses

## FAQ

### Why is there no official OpenAPI spec for BigOven API?

BigOven does not publish an OpenAPI specification - its REST API is documented in narrative form on api2.bigoven.com. Jentic generates and maintains this spec so that AI agents and developers can call BigOven API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the BigOven API use?

Read endpoints use the X-BigOven-API-Key header. User-scoped write endpoints, like grocery list updates and posting reviews, additionally require HTTP Basic credentials for the BigOven account that owns the data. Jentic stores both the API key and the user credential pair separately in the vault and supplies them per call.

### Can I add a whole recipe's ingredients to a grocery list in one call?

Yes. POST `/grocerylist/recipe/{recipeId}` as the authenticated user appends every ingredient from the specified recipe to the user's BigOven grocery list. Follow up with `/grocerylist/departmentalize` to bucket the list by store aisle.

### What are the rate limits for the BigOven API?

BigOven does not publish rate limits in the spec - practical limits depend on the API key tier issued by BigOven. For high-throughput recipe ingestion, batch search calls server-side and cache `/recipe/{recipeId}` responses since recipe content changes infrequently.

### How do I find a random recipe through Jentic?

Run `pip install jentic`, then `await client.search('find a random recipe')`, `await client.load(...)` for BigOven `/recipe/random`, and `await client.execute(...)`. Jentic injects the X-BigOven-API-Key header from the vault and returns the parsed recipe JSON.

### Does the API return nutritional information?

BigOven recipe responses focus on title, ingredients, directions, photos, reviews, and related recipes. Detailed per-serving nutritional facts are not part of this spec - pair with a nutrition-data API if calorie or macro information is required for the integration.

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

Yes. Because you run Jentic One yourself, your own rules decide which BigOven operations and which credentials the agent may use. You can allow read-only calls like /recipes, `/recipe/{recipeId}`, and `/recipe/random` while withholding the HTTP Basic write operations, so adding a recipe to a grocery list through `/grocerylist/recipe/{recipeId}` is not available unless you enable it. Since the recipe id sits in the URL path, a rule can even pin the agent to a single recipe.