Recipe API Documentation

Overview

Recipe API serves structured recipes through one consistent schema: 32 USDA-verified nutrients per serving, grouped ingredients with source traceability, phased cooking instructions with doneness cues, equipment alternatives, storage guidance, and troubleshooting — plus AI recipe generation. The base URL is https://recipe-api.com and data endpoints are versioned under /api/v1.

Try it now — no API key needed:

curl https://recipe-api.com/api/v1/dinner

The machine-readable spec lives at /openapi.json, and there are starter kits and SDK source for TypeScript, Python, and Go.

Authentication

All endpoints except /health and /api/v1/dinner require an API key in the X-API-Key header. Keys look like rapi_<key> — create and manage them on the API keys page (the free plan needs no card).

X-API-Key: rapi_your_key

Keep keys server-side — never in browser JavaScript, query strings, or shared logs. Browsing and discovery calls are free; full recipe detail and ingredient nutrition detail cost 1 credit; generation uses separate generate credits.

Endpoints

Twelve endpoints across three groups: public (no auth), discovery (free with a key), and metered detail/generation calls.

Health check

GET/healthNo authFree

Liveness check. No authentication required.

curl -s "https://recipe-api.com/health"

Response

{ "status": "ok", "timestamp": "2026-06-12T12:00:00.000Z" }

What's for dinner?

GET/api/v1/dinnerNo authFree

Returns a single complete dinner recipe with every field populated — the fastest way to evaluate the schema before signing up. No API key needed.

curl -s "https://recipe-api.com/api/v1/dinner"

Response

{
  "id": "a066f472-ed0c-46ea-8e2c-a0053c3183a8",
  "name": "Texas Chili con Carne",
  "description": "A thick, beef-based stew featuring tender cubes of meat...",
  "category": "Dinner",
  "cuisine": "American",
  "difficulty": "Intermediate",
  "tags": ["Beef", "Slow-Cooked", "High-Protein", "Southwestern"],
  "meta": { "active_time": "PT20M", "total_time": "PT2H", "yields": "4 servings", ... },
  "dietary": { "flags": ["Gluten-Free", "Dairy-Free"], "not_suitable_for": [] },
  "storage": { "refrigerator": { "duration": "P3D", "notes": "..." }, ... },
  "equipment": [ { "name": "Dutch oven", "required": true, "alternative": null }, ... ],
  "ingredients": [ { "group_name": "For the chili", "items": [...] } ],
  "instructions": [ { "step_number": 1, "phase": "prep", "text": "...", "structured": {...} }, ... ],
  "troubleshooting": [ { "symptom": "...", "likely_cause": "...", "prevention": "...", "fix": "..." } ],
  "nutrition": { "per_serving": { "calories": 569, "protein_g": 44.1, ... }, "sources": ["USDA FoodData Central"] }
}

Returns a full Recipe object — see the Recipe object reference below for every field.

List all categories

GET/api/v1/categoriesAPI keyFree

Returns all recipe categories with recipe counts.

curl -s "https://recipe-api.com/api/v1/categories" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    { "name": "Dinner", "count": 245 },
    { "name": "Dessert", "count": 187 },
    ...
  ]
}

List all cuisines

GET/api/v1/cuisinesAPI keyFree

Returns all cuisines with recipe counts.

curl -s "https://recipe-api.com/api/v1/cuisines" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    { "name": "Italian", "count": 156 },
    { "name": "Mexican", "count": 134 },
    ...
  ]
}

List all dietary flags

GET/api/v1/dietary-flagsAPI keyFree

Returns all dietary flags (Vegetarian, Gluten-Free, Vegan, ...) with recipe counts.

curl -s "https://recipe-api.com/api/v1/dietary-flags" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    { "name": "Gluten-Free", "count": 456 },
    { "name": "Vegetarian", "count": 387 },
    { "name": "Dairy-Free", "count": 312 },
    ...
  ]
}

Browse ingredients

GET/api/v1/ingredientsAPI keyFree

Returns a paginated list of 10,000+ ingredients with optional filtering by name or category. Each ingredient carries a stable UUID you can pass to the recipes endpoint.

Query parameters

qstring

Search by ingredient name.

categorystring

Filter by ingredient category.

pageintegerdefault: 1

Page number.

per_pageintegerdefault: 20

Results per page (1–100).

curl -s "https://recipe-api.com/api/v1/ingredients?q=chickpea" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    {
      "id": "001764f3-4d44-4dbc-801b-0e4f094c756d",
      "name": "Chickpeas, canned, drained",
      "category": "Legumes",
      "source": "USDA"
    },
    ...
  ],
  "meta": { "total": 10441, "page": 1, "per_page": 20 }
}

Get ingredient nutrition

GET/api/v1/ingredients/{id}API key1 credit

Returns one ingredient by UUID with its full per-100g USDA nutrition panel. Use an ID from the ingredient list/search endpoint.

Query parameters

iduuidrequired

Ingredient UUID returned by /api/v1/ingredients.

curl -s "https://recipe-api.com/api/v1/ingredients/693538c2-09f5-4a24-9460-0d968be35a2f" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": {
    "id": "693538c2-09f5-4a24-9460-0d968be35a2f",
    "name": "canned chickpeas",
    "category": "Legumes",
    "source": "Aggregated Public Sources",
    "nutrition": {
      "per_100g": {
        "calories": 146.5,
        "protein_g": 7.14,
        "carbohydrates_g": 23.7,
        "fat_g": 2.96,
        "...": "32 nutrients total"
      },
      "sources": ["USDA FoodData Central"]
    }
  },
  "usage": {
    "plan_key": "growth",
    "plan_name": "Production",
    "period_type": "billing_period",
    "detail_used": 1,
    "detail_limit": 60000,
    "detail_remaining": 59999,
    "generation_used": 0,
    "generation_limit": 500,
    "generation_remaining": 500,
    "generation_overage_remaining": 0,
    "reset_at": "2026-08-16T00:00:00.000Z",
    "upgrade_url": "https://recipe-api.com/pricing",
    "monthly_remaining": 59999,
    "monthly_limit": 60000,
    "daily_remaining": 1999,
    "daily_limit": 2000
  }
}

List/search is free discovery and returns IDs only; fetching one ingredient's nutrition by ID is metered.

List all ingredient categories

GET/api/v1/ingredient-categoriesAPI keyFree

Returns all 23 canonical ingredient categories with counts.

curl -s "https://recipe-api.com/api/v1/ingredient-categories" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    { "name": "Vegetables", "count": 1843 },
    { "name": "Legumes", "count": 412 },
    ...
  ]
}

Browse and search recipes

GET/api/v1/recipesAPI keyFree

Returns a paginated list of recipes with optional filtering by text, taxonomy, macros, or ingredients. Browsing is free — discovery is limited to 500 recipes per query, so use filters to narrow larger catalogs.

Query parameters

qstring

Search by name or description.

categorystring

Filter by category.

cuisinestring

Filter by cuisine.

difficultystring

Filter by difficulty: Easy, Intermediate, or Advanced.

dietarystring

Filter by dietary flags (comma-separated).

min_calories / max_caloriesnumber

Calories per serving range.

min_protein / max_proteinnumber

Protein (g) per serving range.

min_carbs / max_carbsnumber

Carbohydrates (g) per serving range.

min_fat / max_fatnumber

Fat (g) per serving range.

ingredientsstring

Comma-separated ingredient UUIDs — returns recipes containing ALL specified ingredients.

pageintegerdefault: 1

Page number (discovery limited to 500 total recipes).

per_pageintegerdefault: 20

Results per page (1–100).

curl -s "https://recipe-api.com/api/v1/recipes?cuisine=Italian&max_calories=600" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": [
    {
      "id": "b177e583-fe1d-57fb-9f3d-b1164d4294b9",
      "name": "Classic Margherita Pizza",
      "description": "Traditional Neapolitan pizza with San Marzano tomatoes...",
      "category": "Dinner",
      "cuisine": "Italian",
      "difficulty": "Easy",
      "tags": ["Vegetarian", "Italian", "Quick"],
      "meta": { "total_time": "PT1H25M", "yields": "2 pizzas", ... },
      "dietary": { "flags": ["Vegetarian"], "not_suitable_for": [] },
      "nutrition_summary": { "calories": 569, "protein_g": 44.1, "carbohydrates_g": 5.6, "fat_g": 42 }
    },
    ...
  ],
  "meta": { "total": 156, "page": 1, "per_page": 20, "total_capped": false }
}

List items include a nutrition_summary (4 macros). The full 32-nutrient breakdown, ingredients, and instructions come from the detail endpoint.

Get full recipe by ID

GET/api/v1/recipes/{id}API key1 credit

Returns complete recipe details — grouped ingredients with USDA-matched UUIDs, phased instructions with structured steps and doneness cues, equipment with alternatives, storage, troubleshooting, and the full 32-nutrient panel. Costs 1 credit; repeat fetches of a recipe you have already unlocked do not count against your unique-recipe quota.

Query parameters

idstring (uuid)required

Recipe UUID.

curl -s "https://recipe-api.com/api/v1/recipes/a066f472-ed0c-46ea-8e2c-a0053c3183a8" \
  -H "X-API-Key: $RECIPE_API_KEY"

Response

{
  "data": { /* full Recipe object — see field reference below */ },
  "usage": {
    "plan_key": "growth",
    "plan_name": "Production",
    "period_type": "billing_period",
    "detail_used": 50,
    "detail_limit": 60000,
    "detail_remaining": 59950,
    "generation_used": 0,
    "generation_limit": 500,
    "generation_remaining": 500,
    "generation_overage_remaining": 0,
    "reset_at": "2026-08-16T00:00:00.000Z",
    "upgrade_url": "https://recipe-api.com/pricing",
    "monthly_remaining": 59950,
    "monthly_limit": 60000,
    "daily_remaining": 1950,
    "daily_limit": 2000
  }
}

Generate a recipe with nutrition

POST/api/v1/generateAPI key1 generate credit

Creates a new recipe from a title and required ingredients, optionally guided by cuisine, difficulty, equipment, time, and notes. Requires generate credits, which are separate from request limits — see Rate limits & quotas below.

Request body

titlestringrequired

Recipe title (max 80 characters).

key_ingredientsstring[]required

Ingredients the recipe must feature (at least 1).

cuisinestring

Optional target cuisine.

difficultystring

Optional target difficulty: Easy, Intermediate, Advanced, or Professional.

equipmentstring[]

Optional available equipment.

timeinteger

Optional target total time in minutes (5–720).

notesstring

Free-form constraints or preferences.

curl -s -X POST "https://recipe-api.com/api/v1/generate" \
  -H "X-API-Key: $RECIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Smoky Chickpea Traybake",
    "key_ingredients": ["chickpeas", "smoked paprika", "red pepper"],
    "cuisine": "Mediterranean",
    "difficulty": "Easy",
    "equipment": ["oven", "sheet pan"],
    "time": 45
  }'

Response

HTTP 201 Created

{
  "data": { /* full generated Recipe object, persisted with a new UUID */ },
  "usage": {
    "plan_key": "indie",
    "plan_name": "Developer",
    "period_type": "billing_period",
    "generation_used": 1,
    "generation_limit": 150,
    "generation_remaining": 149,
    "generation_overage_remaining": 0,
    "reset_at": "2026-08-16T00:00:00.000Z",
    "upgrade_url": "https://recipe-api.com/pricing",
    "daily_remaining": 500,
    "daily_limit": 500,
    "monthly_remaining": 15000,
    "monthly_limit": 15000
  }
}

Generation takes longer than a normal fetch (the recipe and its nutrition are computed on demand) — allow a generous client timeout. A generate credit is consumed after request validation succeeds, before model and nutrition work begins.

Generate food photography

POST/api/v1/image-generateAPI key1 image credit

Generates a photorealistic AI food photograph for an existing recipe. Requires image credits — credit packs are purchased from the dashboard by paid plans. Requests count against your plan's shared per-minute rate limit.

Request body

recipe_idstring (uuid)required

UUID of a public recipe to generate an image for.

aspect_ratiostringdefault: "4:3"

One of 1:1, 3:4, 4:3, 9:16, or 16:9.

curl -s -X POST "https://recipe-api.com/api/v1/image-generate" \
  -H "X-API-Key: $RECIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipe_id": "a066f472-ed0c-46ea-8e2c-a0053c3183a8", "aspect_ratio": "4:3" }' \
  --output recipe.jpg

Response

HTTP 200 — raw JPEG image bytes.

Metadata is returned in response headers:
X-Credits-Remaining, X-Credits-Total, X-Recipe-Id, X-Aspect-Ratio, X-Model

Recipe object

Every recipe — from /dinner, /recipes/{id}, or /generate — uses the same schema. Durations are ISO 8601 (e.g. PT1H15M); all nutrient values are nullable numbers.

idstring (uuid)

Stable recipe identifier.

namestring

Recipe title.

descriptionstring

One-paragraph summary.

categorystring

Recipe category, e.g. Dinner, Dessert.

cuisinestring

Cuisine, e.g. Italian.

difficultystring

Easy, Intermediate, or Advanced.

tagsstring[]

Freeform descriptive tags.

metaobject

Timing and yield: active_time, passive_time, and total_time as ISO 8601 durations (e.g. PT1H15M), overnight_required, yields (e.g. “4 servings”), yield_count, and serving_size_g.

dietaryobject

flags (e.g. Vegetarian, Gluten-Free) and not_suitable_for warnings (e.g. Nut allergy).

storageobject

refrigerator and freezer entries with ISO 8601 durations and notes, reheating guidance, and a does_not_keep flag.

equipmentEquipment[]

Each item has name, required, and a nullable alternative (e.g. “Stand mixer” → “Hand mixer”).

ingredientsIngredientGroup[]

Grouped by component (group_name, e.g. “For the dough”). Each item carries a stable ingredient UUID, name, amounts, one of 23 canonical categories, and a data source (USDA or Aggregated Public Sources).

instructionsInstruction[]

Ordered steps with step_number, phase (prep, cook, assemble, finish), text, tips, and a structured object: action (e.g. ROAST), temperature in both celsius and fahrenheit, ISO 8601 duration, and visual/tactile doneness_cues.

troubleshootingTroubleshooting[]

symptom, likely_cause, prevention, and fix for common failure modes.

chef_notesstring[]

Technique notes.

cultural_contextstring

Background on the dish's origin.

nutritionobject

per_serving with 32 nutrient values plus sources (e.g. [“USDA FoodData Central”]). All values are nullable numbers.

The 32 per-serving nutrients

nutrition.per_serving carries macros, fat breakdown, minerals, and vitamins, calculated from USDA FoodData Central:

caloriesprotein_gcarbohydrates_gfat_gsaturated_fat_gtrans_fat_gmonounsaturated_fat_gpolyunsaturated_fat_gfiber_gsugar_gsodium_mgcholesterol_mgpotassium_mgcalcium_mgiron_mgmagnesium_mgphosphorus_mgzinc_mgvitamin_a_mcgvitamin_c_mgvitamin_d_mcgvitamin_e_mgvitamin_k_mcgvitamin_b6_mgvitamin_b12_mcgthiamin_mgriboflavin_mgniacin_mgfolate_mcgwater_galcohol_gcaffeine_mg

Errors

Every error response uses a single JSON envelope. Switch on the stable error.code, not the message.

{ "error": { "code": "UNAUTHORIZED", "message": "Missing X-API-Key header" } }

Status	Code	Meaning
400	BAD_REQUEST	Invalid JSON body, malformed UUID, or an invalid query parameter.
400	DISCOVERY_LIMIT_EXCEEDED	Page exceeds the 500-recipe discovery limit. Use filters to narrow results.
401	UNAUTHORIZED	Missing or invalid X-API-Key header.
403	FORBIDDEN	Subscription inactive (update billing) or the requested feature is not enabled.
403	PAID_PLAN_REQUIRED	Image credit packs are available to paid subscribers only.
403	NO_IMAGE_CREDITS	No image credits remaining. Purchase a credit pack to continue.
404	NOT_FOUND	Recipe or endpoint not found.
429	RATE_LIMITED	Per-minute rate limit or daily/monthly request quota exceeded. Honor the Retry-After header.
429	UNIQUE_RECIPE_LIMIT_EXCEEDED	Monthly unique-recipe quota reached. Recipes you already unlocked remain accessible.
429	GENERATE_LIMIT_EXCEEDED	Generate credits exhausted (daily or monthly), or generation is not included in your plan.
429	IMAGE_GEN_LIMIT_EXCEEDED	Image generation limit exceeded. Per-minute limiting uses RATE_LIMITED instead.
422	NUTRITION_MATCH_INCOMPLETE	Generated ingredients could not all be matched to nutrition sources; the recipe was not stored. The generate credit has already been consumed.
500	GENERATION_FAILED / NUTRITION_FAILED / DATABASE_ERROR	Something failed on our side. Safe to retry.
500	IMAGE_GENERATION_FAILED	Processing the generated image failed. Credit refunded — safe to retry.
502	INVALID_RECIPE_OUTPUT / IMAGE_GENERATION_FAILED	The AI model returned an unusable result. Image credits are refunded. Please retry.
504	IMAGE_GENERATION_TIMEOUT	Image generation timed out. Credit refunded — please retry.

429 responses include a Retry-After header with the number of seconds to wait.

Rate limits & quotas

Paid requests are limited per minute, per day, and per billing period. The free Evaluation includes 50 lifetime detail requests, 50 unique recipes, and one successful generation; it does not reset. Full recipe detail also counts against the unique-recipe quota, while re-fetching an already unlocked recipe is free. Paid generation has separate daily and billing-period pools.

Plan	Req/min	Req/day	Req/month	Unique recipes/mo	Generate day/mo
Evaluation	10	50	50	50	1 / 1
Developer	20	500	15,000	250	10 / 150
Production	60	2,000	60,000	1,000	25 / 500
Scale	300	10,000	300,000	5,000	50 / 1200

Image generation uses a separate credit balance (500 credits for $125, paid plans only) and counts against your plan's per-minute rate limit. Manage image credits from your dashboard. See plan details for pricing and caching rights.

Tips

Start with GET /api/v1/dinner — it needs no key and shows the complete recipe schema.
Browsing and discovery endpoints are free; only full recipe detail (1 credit) and generation (generate credits) are metered.
Re-fetching a recipe you already unlocked does not consume a new unique-recipe credit — cache locally per your plan's caching rights.
Durations are ISO 8601 (PT45M, PT1H15M, P3D) — parse them rather than string-matching.
All 32 nutrition values are nullable; handle null per nutrient rather than per recipe.
Filter recipes by macro ranges (min_protein, max_calories, ...) server-side instead of fetching detail for each candidate.
Use ingredient UUIDs from /api/v1/ingredients with the recipes ingredients filter to find recipes containing ALL specified ingredients.
Fetch /api/v1/ingredients/{id} when you need one ingredient's full per-100g USDA nutrition values.
Watch the usage object returned with each metered detail fetch to track remaining daily and monthly quota.

MCP connector

Prefer talking to the API from Claude or another MCP client? Add the hosted connector at https://recipe-api.com/api/mcp — it exposes search, recipe detail, and generation as tools. Setup instructions are on the MCP page.