Recipe API Recipes API

openapi: 3.2.0
info:
  title: Recipe Recipes API
  description: 'B2B Recipe API providing structured recipes with comprehensive nutrition data.


    **Quick Start** - Try it now (no API key needed):

    ```

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

    ```


    **Sample Responses** - All endpoints below show example responses so you can evaluate the data structure before signing up. Expand any endpoint to see what you''ll receive.


    **Authentication** - Protected endpoints require an `X-API-Key` header. Get your key at [recipe-api.com](https://recipe-api.com/signup).'
  version: 1.0.0
  contact:
    email: paul@recipe-api.com
servers:
- url: https://recipe-api.com
  description: Production
tags:
- name: Recipes
  description: Browse recipes free. Full recipe detail costs 1 credit. Sample data shown inline.
paths:
  /api/v1/recipes:
    get:
      tags:
      - Recipes
      summary: Browse and search recipes
      description: Returns a paginated list of recipes with optional filtering. Discovery limited to 500 recipes; use filters for larger catalogs. No credit cost.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        description: Search by name or description
        schema:
          type: string
      - name: category
        in: query
        description: Filter by category
        schema:
          type: string
        example: Dinner
      - name: cuisine
        in: query
        description: Filter by cuisine
        schema:
          type: string
        example: Italian
      - name: difficulty
        in: query
        description: Filter by difficulty
        schema:
          type: string
          enum:
          - Easy
          - Intermediate
          - Advanced
          - Professional
      - name: dietary
        in: query
        description: Filter by dietary flags (comma-separated)
        schema:
          type: string
        example: Vegetarian,Gluten-Free
      - name: min_calories
        in: query
        description: Minimum calories per serving
        schema:
          type: number
      - name: max_calories
        in: query
        description: Maximum calories per serving
        schema:
          type: number
      - name: min_protein
        in: query
        description: Minimum protein (g) per serving
        schema:
          type: number
      - name: max_protein
        in: query
        description: Maximum protein (g) per serving
        schema:
          type: number
      - name: min_carbs
        in: query
        description: Minimum carbohydrates (g) per serving
        schema:
          type: number
      - name: max_carbs
        in: query
        description: Maximum carbohydrates (g) per serving
        schema:
          type: number
      - name: min_fat
        in: query
        description: Minimum fat (g) per serving
        schema:
          type: number
      - name: max_fat
        in: query
        description: Maximum fat (g) per serving
        schema:
          type: number
      - name: ingredients
        in: query
        description: Comma-separated ingredient UUIDs (returns recipes containing ALL specified ingredients)
        schema:
          type: string
        example: 3c3f97d4-c951-43fd-865c-88fa8b445739,30109e1e-d8e8-4f76-a6f4-82ac5b071fde
      - name: page
        in: query
        description: Page number (discovery limited to 500 total recipes)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        description: Results per page
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Paginated recipe list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipeListItem'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total matching recipes (capped at 500 for discovery)
                      page:
                        type: integer
                      per_page:
                        type: integer
                      total_capped:
                        type: boolean
                        description: True if more recipes exist beyond the 500-recipe discovery limit
              example:
                data:
                - id: a066f472-ed0c-46ea-8e2c-a0053c3183a8
                  name: Texas Chili con Carne
                  description: A thick, beef-based stew featuring tender cubes of meat in a rich sauce made from reconstituted whole chilies.
                  category: Dinner
                  cuisine: American
                  difficulty: Intermediate
                  tags:
                  - Beef
                  - Slow-Cooked
                  - High-Protein
                  - Southwestern
                  meta:
                    active_time: PT20M
                    passive_time: PT1H40M
                    total_time: PT2H
                    overnight_required: false
                    yields: 4 servings
                    yield_count: 4
                    serving_size_g: 300
                  dietary:
                    flags:
                    - Gluten-Free
                    - Dairy-Free
                    - Nut-Free
                    not_suitable_for: []
                  nutrition_summary:
                    calories: 569
                    protein_g: 44.1
                    carbohydrates_g: 5.6
                    fat_g: 42
                - id: b177e583-fe1d-57fb-9f3d-b1164d4294b9
                  name: Classic Margherita Pizza
                  description: Traditional Neapolitan pizza with San Marzano tomatoes, fresh mozzarella, basil, and olive oil on a thin, crispy crust.
                  category: Dinner
                  cuisine: Italian
                  difficulty: Easy
                  tags:
                  - Vegetarian
                  - Italian
                  - Quick
                  meta:
                    active_time: PT25M
                    passive_time: PT1H
                    total_time: PT1H25M
                    overnight_required: false
                    yields: 2 pizzas
                    yield_count: 2
                    serving_size_g: 250
                  dietary:
                    flags:
                    - Vegetarian
                    - Nut-Free
                    not_suitable_for:
                    - Lactose intolerant
                  nutrition_summary:
                    calories: 320
                    protein_g: 14.5
                    carbohydrates_g: 38.2
                    fat_g: 12.8
                meta:
                  total: 500
                  page: 1
                  per_page: 20
                  total_capped: true
        '400':
          description: Discovery limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: DISCOVERY_LIMIT_EXCEEDED
                  message: Page exceeds discovery limit. Maximum 500 recipes accessible. Use filters to narrow results.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/recipes/{id}:
    get:
      tags:
      - Recipes
      summary: Get full recipe by ID
      description: Returns complete recipe details including ingredients, instructions, and nutrition. **Costs 1 credit.**
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Recipe UUID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Full recipe details with usage info
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Recipe'
                  usage:
                    $ref: '#/components/schemas/Usage'
              example:
                data:
                  id: a066f472-ed0c-46ea-8e2c-a0053c3183a8
                  name: Texas Chili con Carne
                  description: A thick, beef-based stew featuring tender cubes of meat in a rich sauce made from reconstituted whole chilies and aromatic spices without beans or tomatoes.
                  category: Dinner
                  cuisine: American
                  difficulty: Intermediate
                  tags:
                  - Beef
                  - Slow-Cooked
                  - High-Protein
                  - Southwestern
                  meta:
                    active_time: PT20M
                    passive_time: PT1H40M
                    total_time: PT2H
                    overnight_required: false
                    yields: 4 servings
                    yield_count: 4
                    serving_size_g: 300
                  dietary:
                    flags:
                    - Gluten-Free
                    - Dairy-Free
                    - Egg-Free
                    - Nut-Free
                    - Peanut-Free
                    - Soy-Free
                    not_suitable_for: []
                  storage:
                    refrigerator:
                      duration: P4D
                      notes: Flavor improves after 24 hours.
                    freezer:
                      duration: P3M
                      notes: Thaw overnight in refrigerator before reheating.
                    reheating: Heat in a saucepan over medium-low heat, adding a splash of water if too thick.
                    does_not_keep: false
                  equipment:
                  - name: Blender
                    required: true
                    alternative: Food processor or mortar and pestle
                  - name: Heavy skillet
                    required: true
                    alternative: Dutch oven or heavy-bottomed pot
                  - name: Mixing bowl
                    required: true
                    alternative: null
                  ingredients:
                  - group_name: Chili Base
                    items:
                    - name: red chilies
                      quantity: 6
                      unit: null
                      preparation: dried
                      notes: about 30g
                      substitutions: []
                      ingredient_id: 3c3f97d4-c951-43fd-865c-88fa8b445739
                      nutrition_source: USDA FoodData Central
                    - name: stewing beef
                      quantity: 910
                      unit: g
                      preparation: cut into 1.3cm (1/2 inch) cubes
                      notes: null
                      substitutions: []
                      ingredient_id: 09f2eef4-739a-4fca-8b63-97d697257990
                      nutrition_source: USDA FoodData Central
                    - name: olive oil
                      quantity: 15
                      unit: ml
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: e9f370c4-07c8-4d8d-8a9f-0edea38db44c
                      nutrition_source: USDA FoodData Central
                    - name: bay leaves
                      quantity: 2
                      unit: null
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: eab2ef3a-7a0e-4188-b746-645b795ada1e
                      nutrition_source: USDA FoodData Central
                  - group_name: Flavor Paste
                    items:
                    - name: garlic
                      quantity: 2
                      unit: null
                      preparation: peeled
                      notes: about 6g
                      substitutions: []
                      ingredient_id: 30109e1e-d8e8-4f76-a6f4-82ac5b071fde
                      nutrition_source: USDA FoodData Central
                    - name: cumin
                      quantity: 7
                      unit: g
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: b9c9e3cb-61b7-4bbc-87c0-7858d42d7935
                      nutrition_source: USDA FoodData Central
                    - name: oregano
                      quantity: 3
                      unit: g
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: 687f54eb-e811-4e5e-ac2e-e2735458480c
                      nutrition_source: USDA FoodData Central
                    - name: paprika
                      quantity: 14
                      unit: g
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: f4c3bdd7-6528-40d2-84b3-a6325df15e8e
                      nutrition_source: USDA FoodData Central
                    - name: sugar
                      quantity: 4
                      unit: g
                      preparation: null
                      notes: null
                      substitutions: []
                      ingredient_id: 8ae7f905-b311-4f45-9527-5e3840369506
                      nutrition_source: USDA FoodData Central
                    - name: salt
                      quantity: null
                      unit: null
                      preparation: null
                      notes: to taste
                      substitutions: []
                      ingredient_id: 2631739c-2de4-4389-a6e3-ed3d06d0406f
                      nutrition_source: USDA FoodData Central
                    - name: black pepper
                      quantity: null
                      unit: null
                      preparation: null
                      notes: to taste
                      substitutions: []
                      ingredient_id: c25dc1c9-4ea7-403c-976e-ab1d06578b7a
                      nutrition_source: USDA FoodData Central
                  instructions:
                  - step_number: 1
                    phase: prep
                    text: Tear the dried chilies into strips and place them in a bowl. Cover with 240ml (1 cup) of boiling water and soak for 30 minutes.
                    structured:
                      action: SOAK
                      temperature: null
                      duration: PT30M
                      doneness_cues: null
                    tips: []
                  - step_number: 2
                    phase: prep
                    text: Drain the chilies and set them aside. Reserve the soaking liquid for the cooking process.
                    structured:
                      action: DRAIN
                      temperature: null
                      duration: null
                      doneness_cues: null
                    tips: []
                  - step_number: 3
                    phase: cook
                    text: Heat olive oil in a heavy skillet over medium-high heat. Brown the beef cubes on all sides until a crust forms.
                    structured:
                      action: SEAR
                      temperature: null
                      duration: null
                      doneness_cues:
                        visual: Beef is deeply browned on all sides
                        tactile: null
                    tips: []
                  - step_number: 4
                    phase: cook
                    text: Pour the reserved chili soaking liquid into the skillet. Add bay leaves and bring the liquid to a boil.
                    structured:
                      action: BOIL
                      temperature: null
                      duration: null
                      doneness_cues: null
                    tips: []
                  - step_number: 5
                    phase: cook
                    text: Reduce the heat to low, cover the skillet, and simmer for 1 hour.
                    structured:
                      action: SIMMER
                      temperature:
                        celsius: 90
                        fahrenheit: 194
                      duration: PT1H
                      doneness_cues: null
                    tips: []
                  - step_number: 6
                    phase: prep
                    text: Combine the soaked chilies, garlic, cumin, oregano, paprika, sugar, salt, and pepper in a blender. Puree until smooth, adding a small amount of fresh water if the mixture is too thick.
                    structured:
                      action: PUREE
                      temperature: null
                      duration: null
                      doneness_cues: null
                    tips: []
                  - step_number: 7
                    phase: cook
                    text: Stir the chili puree into the skillet with the beef. Cover and continue to simmer for 30 minutes.
                    structured:
                      action: SIMMER
                      temperature: null
                      duration: PT30M
                      doneness_cues:
                        visual: null
                        tactile: Beef cubes are fork-tender
                    tips: []
                  - step_number: 8
                    phase: finish
                    text: Remove and discard the bay leaves. Taste and add more salt or pepper if needed before serving.
                    structured:
                      action: SERVE
                      temperature: null
                      duration: null
                      doneness_cues: null
                    tips: []
                  troubleshooting:
                  - symptom: Beef is tough or chewy
                    likely_cause: The meat has not simmered long enough to break down connective tissue.
                    prevention: Ensure the liquid is at a very low simmer and the lid is tightly sealed.
                    fix: Continue simmering in 15-minute increments until tender.
                  - symptom: Chili is too watery
                    likely_cause: Too much water added during blending or insufficient reduction.
                    prevention: Add water to the blender only 15ml at a time.
                    fix: Simmer uncovered for the final 15 minutes to evaporate excess moisture.
                  chef_notes:
                  - For the deepest chili flavor, use a variety of dried chilies like ancho, guajillo, and pasilla. Toasting them briefly before soaking can enhance their aroma.
                  - Don't overcrowd the skillet when browning the beef; sear in batches if necessary to ensure a good crust, which adds significant flavor to the final dish.
                  - The simmering time is crucial for tenderizing the beef. Low and slow is key; the meat should be easily pierced with a fork.
                  - The consistency of the chili can be adjusted by the amount of soaking liquid you use and the final simmering time. If it's too thick, add a splash of water or beef broth; if too thin, simmer uncovered for a bit longer.
                  cultural_context: Texas Chili, or Chili con Carne, is a hearty stew deeply rooted in Texan culinary tradition. Its origins trace back to the mid-19th century, with early versions featuring simple ingredients like dried beef, chilies, and spices, cooked by cowboys and ranchers. The absence of beans and tomatoes is a defining characteristic, distinguishing it from other regional chili variations and emphasizing its pure, meat-and-chili flavor profile.
                  nutrition:
                    per_serving:
                      calories: 569.02
                      protein_g: 44.14
                      carbohydrates_g: 5.59
                      fat_g: 41.99
                      saturated_fat_g: 16.48
                      trans_fat_g: 2.39
                      monounsaturated_fat_g: 20.66
                      polyunsaturated_fat_g: 2.29
                      fiber_g: 1.97
                      sugar_g: 1.84
                      sodium_mg: 350.75
                      cholesterol_mg: 154.7
                      potassium_mg: 903.3
                      calcium_mg: 74.24
                      iron_mg: 7.16
                      magnesium_mg: 60.57
                      phosphorus_mg: 434.12
                      zinc_mg: 16.82
                      vitamin_a_mcg: 101.01
                      vitamin_c_mg: 11.51
                      vitamin_d_mcg: 0.23
                      vitamin_e_mg: 2.15
                      vitamin_k_mcg: 14.73
                      vitamin_b6_mg: 0.97
                      vitamin_b12_mcg: 6.14
                      thiamin_mg: 0.19
                      riboflavin_mg: 0.38
                      niacin_mg: 10.47
                      folate_mcg: 12.53
                      water_g: 154.87
                      alcohol_g: null
                      caffeine_mg: null
                    sources:
                    - USDA FoodData Central
                usage:
                  monthly_remaining: 1950
                  monthly_limit: 2000
                  daily_remaining: 95
                  daily_limit: 100
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/generate:
    post:
      tags:
      - Recipes
      summary: Generate a recipe with nutrition
      description: Creates a new recipe from a title and required ingredients, optionally guided by cuisine, difficulty, equipment, time, and notes. Requires generate credits separate from normal request limits. A generate credit is consumed after request validation succeeds, before model and nutrition work begins.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequest'
            example:
              title: Lemon Herb Chicken
              key_ingredients:
              - chicken breast
              - lemon
              - garlic
              - olive oil
              cuisine: Mediterranean
              difficulty: Easy
              equipment:
              - skillet
              time: 35
              notes: Weeknight-friendly, bright and zesty.
      parameters:
      - name: dry_run
        in: query
        required: false
        schema:
          type: boolean
        description: Return usage and generated content without persisting. Only available when ENABLE_GENERATE_DRY_RUN=true.
      responses:
        '201':
          description: Generated recipe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: 'Nutrition matching incomplete. One or more generated ingredients could not be matched to a nutrition source, so the recipe was not stored. Note: the generate credit is consumed after request validation, so this failure occurs after the credit has been spent and it is not refunded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NUTRITION_MATCH_INCOMPLETE
                  message: All ingredients must match nutrition sources.
        '429':
          description: Generate limit reached. Returned when daily or monthly generate credits are exhausted, when the per-minute rate limit is hit, or when recipe generation is not included in your plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                daily_limit:
                  summary: Daily generate credits exhausted
                  value:
                    error:
                      code: GENERATE_LIMIT_EXCEEDED
                      message: Daily generate limit reached (10). Try again tomorrow.
                monthly_limit:
                  summary: Monthly generate credits exhausted
                  value:
                    error:
                      code: GENERATE_LIMIT_EXCEEDED
                      message: Monthly generate limit reached (150). Upgrade your plan for more.
                not_in_plan:
                  summary: Generation not included in plan
                  value:
                    error:
                      code: GENERATE_LIMIT_EXCEEDED
                      message: Recipe generation is not included in your plan. See https://recipe-api.com/compare to add it.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying (present when the per-minute rate limit triggered the 429)
        '500':
          description: Generation pipeline error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                generation_failed:
                  summary: Model call failed
                  value:
                    error:
                      code: GENERATION_FAILED
                      message: Failed to generate recipe.
                nutrition_failed:
                  summary: Nutrition calculation failed
                  value:
                    error:
                      code: NUTRITION_FAILED
                      message: Failed to calculate nutrition.
                database_error:
                  summary: Failed to store the generated recipe
                  value:
                    error:
                      code: DATABASE_ERROR
                      message: Failed to store recipe.
        '502':
          description: Generation output invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_RECIPE_OUTPUT
                  message: Generated recipe did not match required schema.
components:
  schemas:
    Ingredient:
      type: object
      properties:
        name:
          type: string
          example: all-purpose flour
        quantity:
          type:
          - number
          - 'null'
          example: 2.5
        unit:
          type:
          - string
          - 'null'
          example: cups
        preparation:
          type:
          - string
          - 'null'
          example: sifted
        notes:
          type:
          - string
          - 'null'
        substitutions:
          type: array
          items:
            type: string
        ingredient_id:
          type:
          - string
          - 'null'
          format: uuid
        nutrition_source:
          type:
          - string
          - 'null'
          example: USDA FoodData Central
    RecipeResponse:
      type: object
      description: Response from generate endpoint containing the created recipe and usage info
      properties:
        data:
          $ref: '#/components/schemas/Recipe'
        usage:
          $ref: '#/components/schemas/Usage'
    StructuredStep:
      type:
      - object
      - 'null'
      properties:
        action:
          type: string
          example: ROAST
        temperature:
          type:
          - object
          - 'null'
          properties:
            celsius:
              type: integer
              example: 200
            fahrenheit:
              type: integer
              example: 392
        duration:
          type:
          - string
          - 'null'
          description: ISO 8601 duration
          example: PT25M
        doneness_cues:
          type:
          - object
          - 'null'
          properties:
            visual:
              type:
              - string
              - 'null'
              example: Golden brown edges
            tactile:
              type:
              - string
              - 'null'
              example: Springs back when pressed
    Nutrition:
      type: object
      properties:
        per_serving:
          type: object
          properties:
            calories:
              type:
              - number
              - 'null'
            protein_g:
              type:
              - number
              - 'null'
            carbohydrates_g:
              type:
              - number
              - 'null'
            fat_g:
              type:
              - number
              - 'null'
            saturated_fat_g:
              type:
              - number
              - 'null'
            trans_fat_g:
              type:
              - number
              - 'null'
            monounsaturated_fat_g:
              type:
              - number
              - 'null'
            polyunsaturated_fat_g:
              type:
              - number
              - 'null'
            fiber_g:
              type:
              - number
              - 'null'
            sugar_g:
              type:
              - number
              - 'null'
            sodium_mg:
              type:
              - number
              - 'null'
            cholesterol_mg:
              type:
              - number
              - 'null'
            potassium_mg:
              type:
              - number
              - 'null'
            calcium_mg:
              type:
              - number
              - 'null'
            iron_mg:
              type:
              - number
              - 'null'
            magnesium_mg:
              type:
              - number
              - 'null'
            phosphorus_mg:
              type:
              - number
              - 'null'
            zinc_mg:
              type:
              - number
              - 'null'
            vitamin_a_mcg:
              type:
              - number
              - 'null'
            vitamin_c_mg:
              type:
              - number
              - 'null'
            vitamin_d_mcg:
              type:
              - number
              - 'null'
            vitamin_e_mg:
              type:
              - number
              - 'null'
            vitamin_k_mcg:
              type:
              - number
              - 'null'
            vitamin_b6_mg:
              type:
              - number
              - 'null'
            vitamin_b12_mcg:
              type:
              - number
              - 'null'
            thiamin_mg:
              type:
              - number
              - 'null'
            riboflavin_mg:
              type:
              - number
              - 'null'
            niacin_mg:
              type:
              - number
              - 'null'
            folate_mcg:
              type:
              - number
              - 'null'
            water_g:
              type:
              - number
              - 'null'
            alcohol_g:
              type:
              - number
              - 'null'
            caffeine_mg:
              type:
              - number
              - 'null'
        sources:
          type: array
          items:
            type: string
          example:
          - USDA FoodData Central
    Dietary:
      type: object
      properties:
        flags:
          type: array
          items:
            type: string
          example:
          - Vegetarian
          - Gluten-Free
        not_suitable_for:
          type: array
          items:
            type: str

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/recipe-api/refs/heads/main/openapi/recipe-api-recipes-api-openapi.yml