Generate Endpoint

Overview

The Generate endpoint creates brand-new recipes from structured constraints. You provide the recipe title, key ingredients, cuisine, difficulty, equipment, and target cooking time. The API generates a complete recipe with:

• ✓ Full structured ingredients with quantities, units, and substitutions
• ✓ Step-by-step instructions with temperatures, durations, and doneness cues
• ✓ 32 USDA-verified nutrition values per serving
• ✓ Dietary flags, storage instructions, troubleshooting tips, and chef notes

Rate Limits

Generate requests have separate daily and monthly limits from regular API requests:

Per-minute rate limits also apply. If exceeded, you'll receive a 429 response.

Request Schema

Send a POST request with a JSON body containing the following fields:

Example Request

{
  "title": "Lemon Herb Roasted Chicken",
  "key_ingredients": [
    "whole chicken",
    "lemon",
    "garlic",
    "rosemary",
    "thyme",
    "olive oil",
    "butter"
  ],
  "cuisine": "Mediterranean",
  "difficulty": "Intermediate",
  "equipment": [
    "roasting pan",
    "meat thermometer"
  ],
  "time": 90,
  "notes": "Crispy skin is essential. Include a pan sauce from drippings."
}

Response Schema

On success (201 Created), the response contains the full recipe and usage information:

Top-Level Response

Recipe Object

Meta Object

Equipment Object

IngredientGroup Object

Ingredient Object

Instruction Object

StructuredStep Object

Nutrition Object (32 nutrients)

per_serving fields:

Usage Object

Full Example

Request

curl -X POST https://recipe-api.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rapi_your_key" \
  -d '{
    "title": "Garlic Butter Shrimp Pasta",
    "key_ingredients": ["shrimp", "linguine", "garlic", "butter", "white wine", "parsley", "lemon"],
    "cuisine": "Italian",
    "difficulty": "Easy",
    "equipment": ["large pot", "skillet"],
    "time": 30,
    "notes": "Quick weeknight dinner. Should be garlicky and buttery."
  }'

Response (201 Created)

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Garlic Butter Shrimp Pasta",
    "description": "A quick and elegant pasta dish featuring succulent shrimp tossed in a rich garlic butter sauce with white wine and fresh herbs.",
    "category": "Dinner",
    "cuisine": "Italian",
    "difficulty": "Easy",
    "tags": ["seafood", "pasta", "quick", "weeknight"],
    "meta": {
      "active_time": "PT25M",
      "passive_time": "PT5M",
      "total_time": "PT30M",
      "overnight_required": false,
      "yields": "4 servings",
      "yield_count": 4,
      "serving_size_g": 350
    },
    "dietary": {
      "flags": [],
      "not_suitable_for": ["Shellfish allergy", "Dairy allergy"]
    },
    "storage": {
      "refrigerator": { "duration": "P2D", "notes": "Store pasta and shrimp separately" },
      "freezer": null,
      "reheating": "Reheat gently in a skillet with a splash of water",
      "does_not_keep": false
    },
    "equipment": [
      { "name": "Large pot", "required": true, "alternative": null },
      { "name": "Skillet", "required": true, "alternative": "Saute pan" }
    ],
    "ingredients": [
      {
        "group_name": "Main",
        "items": [
          {
            "name": "linguine",
            "quantity": 400,
            "unit": "g",
            "preparation": null,
            "notes": null,
            "substitutions": ["spaghetti", "fettuccine"],
            "ingredient_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "nutrition_source": "USDA FoodData Central"
          },
          {
            "name": "large shrimp",
            "quantity": 500,
            "unit": "g",
            "preparation": "peeled and deveined",
            "notes": "About 24 shrimp",
            "substitutions": ["prawns"],
            "ingredient_id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
            "nutrition_source": "USDA FoodData Central"
          },
          {
            "name": "garlic",
            "quantity": 6,
            "unit": "cloves",
            "preparation": "minced",
            "notes": null,
            "substitutions": [],
            "ingredient_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
            "nutrition_source": "USDA FoodData Central"
          },
          {
            "name": "unsalted butter",
            "quantity": 60,
            "unit": "g",
            "preparation": null,
            "notes": null,
            "substitutions": ["olive oil for dairy-free"],
            "ingredient_id": "550e8400-e29b-41d4-a716-446655440000",
            "nutrition_source": "USDA FoodData Central"
          }
        ]
      }
    ],
    "instructions": [
      {
        "step_number": 1,
        "phase": "prep",
        "text": "Bring a large pot of salted water to a boil. Cook linguine according to package directions until al dente. Reserve 1 cup pasta water before draining.",
        "structured": {
          "action": "BOIL",
          "temperature": null,
          "duration": "PT10M",
          "doneness_cues": {
            "visual": null,
            "tactile": "Pasta should be tender but firm when bitten"
          }
        },
        "tips": ["Salt the water generously - it should taste like the sea"]
      },
      {
        "step_number": 2,
        "phase": "cook",
        "text": "In a large skillet, melt butter over medium-high heat. Add shrimp in a single layer and cook until pink on one side, about 2 minutes. Flip and cook 1 minute more. Remove to a plate.",
        "structured": {
          "action": "SAUTE",
          "temperature": { "celsius": 190, "fahrenheit": 375 },
          "duration": "PT3M",
          "doneness_cues": {
            "visual": "Shrimp turn pink and opaque",
            "tactile": "Firm but springy"
          }
        },
        "tips": ["Don't overcrowd the pan or shrimp will steam instead of sear"]
      }
    ],
    "troubleshooting": [
      {
        "symptom": "Shrimp are rubbery",
        "likely_cause": "Overcooked",
        "prevention": "Remove shrimp as soon as they turn pink",
        "fix": "Cannot be fixed once overcooked"
      }
    ],
    "chef_notes": [
      "The pasta water is key - its starch helps create a silky sauce",
      "Add the garlic after the shrimp to prevent burning"
    ],
    "cultural_context": "This dish draws from Italian-American cuisine, combining the simplicity of aglio e olio with the richness of scampi.",
    "nutrition": {
      "per_serving": {
        "calories": 542,
        "protein_g": 32.5,
        "carbohydrates_g": 58.2,
        "fat_g": 18.4,
        "saturated_fat_g": 9.1,
        "trans_fat_g": 0.5,
        "fiber_g": 2.8,
        "sugar_g": 2.1,
        "sodium_mg": 485,
        "cholesterol_mg": 215,
        "...": "(32 total nutrients)"
      },
      "sources": ["USDA FoodData Central"]
    }
  },
  "usage": {
    "daily_remaining": 4,
    "daily_limit": 5,
    "monthly_remaining": 95,
    "monthly_limit": 100
  }
}

Error Codes