Spoonacular Meal Planning API

openapi: 3.0.0
info:
  title: spoonacular Ingredients Meal Planning API
  description: 'The spoonacular Nutrition, Recipe, and Food API allows you to access over thousands of recipes, thousands of ingredients, 800,000 food products, over 100,000 menu items, and restaurants. Our food ontology and semantic recipe search engine makes it possible to search for recipes using natural language queries, such as "gluten free brownies without sugar" or "low fat vegan cupcakes." You can automatically calculate the nutritional information for any recipe, analyze recipe costs, visualize ingredient lists, find recipes for what''s in your fridge, find recipes based on special diets, nutritional requirements, or favorite ingredients, classify recipes into types and cuisines, convert ingredient amounts, or even compute an entire meal plan. With our powerful API, you can create many kinds of food and especially nutrition apps.


    Special diets/dietary requirements currently available include: vegan, vegetarian, pescetarian, gluten free, grain free, dairy free, high protein, whole 30, low sodium, low carb, Paleo, ketogenic, FODMAP, and Primal.'
  contact:
    name: David Urbansky
    email: mail@spoonacular.com
    url: https://spoonacular.com/contact
  version: 2.0.2
  x-codegen-settings:
    Nullify404: false
    GenerateAsyncCode: true
    UseMethodPrefix: true
    UseModelPostfix: false
    UseControllerPrefix: true
    UseEnumPostfix: true
    CollectParameters: false
    UseConstructorsForConfig: true
    UseCommonSDKLibrary: false
    iOSUseAppInfoPlist: true
    AndroidUseAppManifest: true
    BodySerialization: 0
    EnableAdditionalModelProperties: false
    PreserveParameterOrder: false
    AppendContentHeaders: true
    iOSGenerateCoreData: false
    GenerateInterfaces: false
    NodeHttpClient: NODE_REQUEST
    ValidateRequiredParameters: false
    JavaUsePropertiesConfig: false
    Timeout: 0
    StoreTimezoneInformation: false
    EnablePHPComposerVersionString: false
    EnableLogging: false
    ArraySerialization: Indexed
    ModelSerializationScheme: Json
    UseExceptionPrefix: true
    RunscopeEnabled: false
    JavaHttpClient: JAVA_OK
    ParameterArrayFormat: ParamArrayWithIndex
    SecurityProtocols:
    - Ssl3
    - Tls
    GenerateTravisConfig: false
    GenerateCircleConfig: false
    GenerateAppveyorConfig: false
    GenerateJenkinsConfig: false
    EnableHttpCache: false
    Retries: 0
    RetryInterval: 1
    GenerateAdvancedDocs: false
    UnderscoreNumbers: true
    UseSingletonPattern: true
    DisableLinting: false
    ApplyCustomizations: []
    SortResources: false
    AllowSkippingSSLCertVerification: false
    DoNotSplitWords: []
    EnableGlobalUserAgent: true
    ReturnCompleteHttpResponse: false
    GenerateModels: true
    GenerateExceptions: true
    IgnoreIfNullJson: false
    DisableDocs: false
    LiftParameterDescriptionFromCustomType: false
    ThrowForHttpErrorStatusCodes: true
    ResponseMapping:
      Type: Simple
    ForceKeywordArgsInRuby: false
    SymbolizeHashKeysInRuby: false
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
    - name: production
      servers:
      - name: default
        url: https://api.spoonacular.com
    parameters: []
  license:
    name: spoonacular API Terms
    url: https://spoonacular.com/food-api/terms
  termsOfService: https://spoonacular.com/food-api/terms
  x-apis-json-aid: spoonacular
  x-spec-source: https://github.com/ddsky/spoonacular-api-clients/blob/master/spoonacular-openapi-3.json
  x-last-validated: '2026-06-03'
  x-providerName: spoonacular.com
servers:
- url: https://api.spoonacular.com
  variables: {}
security:
- apiKeyScheme: []
tags:
- name: Meal Planning
paths:
  /mealplanner/generate:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  meals:
                    type: array
                    uniqueItems: true
                    minItems: 0
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        title:
                          type: string
                          minLength: 1
                        imageType:
                          type: string
                          minLength: 1
                        readyInMinutes:
                          type: integer
                        servings:
                          type: number
                        sourceUrl:
                          type: string
                          minLength: 1
                      required:
                      - id
                      - title
                      - imageType
                      - readyInMinutes
                      - servings
                      - sourceUrl
                  nutrients:
                    type: object
                    required:
                    - calories
                    - carbohydrates
                    - fat
                    - protein
                    properties:
                      calories:
                        type: number
                      carbohydrates:
                        type: number
                      fat:
                        type: number
                      protein:
                        type: number
                required:
                - meals
                - nutrients
              examples:
                example-1:
                  value:
                    meals:
                    - id: 655219
                      title: Peanut Butter And Chocolate Oatmeal
                      imageType: jpg
                      readyInMinutes: 45
                      servings: 1
                      sourceUrl: https://spoonacular.com/recipes/peanut-butter-and-chocolate-oatmeal-655219
                    - id: 649931
                      title: Lentil Salad With Vegetables
                      imageType: jpg
                      readyInMinutes: 45
                      servings: 4
                      sourceUrl: https://spoonacular.com/recipes/lentil-salad-with-vegetables-649931
                    - id: 632854
                      title: Asian Noodles
                      imageType: jpg
                      readyInMinutes: 45
                      servings: 4
                      sourceUrl: https://spoonacular.com/recipes/asian-noodles-632854
                    nutrients:
                      calories: 1735.81
                      carbohydrates: 235.17
                      fat: 69.22
                      protein: 55.43
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: timeFrame
        description: Either for one "day" or an entire "week".
        schema:
          type: string
          example: day
        required: false
        style: form
        explode: false
        in: query
        example: day
      - name: targetCalories
        description: What is the caloric target for one day? The meal plan generator will try to get as close as possible to that goal.
        schema:
          type: number
          example: 2000
        required: false
        style: form
        explode: false
        in: query
        example: 2000
      - name: diet
        description: Enter a diet that the meal plan has to adhere to. See a full list of supported diets.
        schema:
          type: string
          example: vegetarian
        required: false
        style: form
        explode: false
        in: query
        example: vegetarian
      - name: exclude
        description: A comma-separated list of allergens or ingredients that must be excluded.
        schema:
          type: string
          example: shellfish, olives
        required: false
        style: form
        explode: false
        in: query
        example: shellfish, olives
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Generate-Meal-Plan
      summary: Generate Meal Plan
      description: Generate a meal plan with three meals per day (breakfast, lunch, and dinner).
      operationId: generateMealPlan
      deprecated: false
      tags:
      - Meal Planning
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /mealplanner/{username}/week/{start_date}:
    get:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  days:
                    type: array
                    uniqueItems: true
                    minItems: 0
                    items:
                      type: object
                      properties:
                        nutritionSummary:
                          type: object
                          properties:
                            nutrients:
                              type: array
                              uniqueItems: true
                              minItems: 0
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    minLength: 1
                                  amount:
                                    type: number
                                  unit:
                                    type: string
                                    minLength: 1
                                  percentDailyNeeds:
                                    type: number
                                required:
                                - name
                                - amount
                                - unit
                                - percentDailyNeeds
                          required:
                          - nutrients
                        nutritionSummaryBreakfast:
                          type: object
                          properties:
                            nutrients:
                              type: array
                              uniqueItems: true
                              minItems: 0
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    minLength: 1
                                  amount:
                                    type: number
                                  unit:
                                    type: string
                                    minLength: 1
                                  percentDailyNeeds:
                                    type: number
                                required:
                                - name
                                - amount
                                - unit
                                - percentDailyNeeds
                          required:
                          - nutrients
                        nutritionSummaryLunch:
                          type: object
                          properties:
                            nutrients:
                              type: array
                              uniqueItems: true
                              minItems: 0
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    minLength: 1
                                  amount:
                                    type: number
                                  unit:
                                    type: string
                                    minLength: 1
                                  percentDailyNeeds:
                                    type: number
                                required:
                                - name
                                - amount
                                - unit
                                - percentDailyNeeds
                          required:
                          - nutrients
                        nutritionSummaryDinner:
                          type: object
                          properties:
                            nutrients:
                              type: array
                              uniqueItems: true
                              minItems: 0
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    minLength: 1
                                  amount:
                                    type: number
                                  unit:
                                    type: string
                                    minLength: 1
                                  percentDailyNeeds:
                                    type: number
                                required:
                                - name
                                - amount
                                - unit
                                - percentDailyNeeds
                          required:
                          - nutrients
                        date:
                          type: number
                        day:
                          type: string
                          minLength: 1
                        items:
                          type: array
                          uniqueItems: true
                          minItems: 0
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              slot:
                                type: integer
                              position:
                                type: integer
                              type:
                                type: string
                                minLength: 1
                              value:
                                type: object
                                properties:
                                  servings:
                                    type: number
                                  id:
                                    type: number
                                  title:
                                    type: string
                                    minLength: 1
                                  imageType:
                                    type: string
                                required:
                                - servings
                                - id
                                - title
                                - imageType
                            required:
                            - id
                            - slot
                            - position
                            - type
                      required:
                      - date
                      - day
                required:
                - days
              examples:
                example-1:
                  value:
                    days:
                    - nutritionSummary:
                        nutrients:
                        - name: Calories
                          amount: 310
                          unit: cal
                          percentDailyNeeds: 16
                        - name: Fat
                          amount: 25
                          unit: g
                          percentDailyNeeds: 38
                        - name: Carbohydrates
                          amount: 1
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 20
                          unit: g
                          percentDailyNeeds: 40
                      nutritionSummaryBreakfast:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      nutritionSummaryLunch:
                        nutrients:
                        - name: Calories
                          amount: 310
                          unit: cal
                          percentDailyNeeds: 16
                        - name: Fat
                          amount: 25
                          unit: g
                          percentDailyNeeds: 38
                        - name: Carbohydrates
                          amount: 1
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 20
                          unit: g
                          percentDailyNeeds: 40
                      nutritionSummaryDinner:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      date: 1589155200
                      day: Monday
                      items:
                      - id: 1976489
                        slot: 1
                        position: 1
                        type: RECIPE
                        value:
                          servings: 2
                          id: 1023004
                          title: Foolproof Meatloaf
                          imageType: ''
                      - id: 1976490
                        slot: 2
                        position: 2
                        type: CUSTOM_FOOD
                        value:
                          servings: 1
                          id: 345
                          title: Denn's Lamb Bratwurst - 1/2 Pkg
                          image: https://spoonacular.com/cdn/ingredients_100x100/bratwurst.jpg
                          imageType: jpg
                    - nutritionSummary:
                        nutrients:
                        - name: Calories
                          amount: 200
                          unit: cal
                          percentDailyNeeds: 10
                        - name: Fat
                          amount: 1
                          unit: g
                          percentDailyNeeds: 1
                        - name: Carbohydrates
                          amount: 52
                          unit: g
                          percentDailyNeeds: 17
                        - name: Protein
                          amount: 2
                          unit: g
                          percentDailyNeeds: 4
                      nutritionSummaryBreakfast:
                        nutrients:
                        - name: Calories
                          amount: 200
                          unit: cal
                          percentDailyNeeds: 10
                        - name: Fat
                          amount: 1
                          unit: g
                          percentDailyNeeds: 1
                        - name: Carbohydrates
                          amount: 52
                          unit: g
                          percentDailyNeeds: 17
                        - name: Protein
                          amount: 2
                          unit: g
                          percentDailyNeeds: 4
                      nutritionSummaryLunch:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      nutritionSummaryDinner:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      date: 1589241600
                      day: Tuesday
                      items:
                      - id: 1976491
                        slot: 1
                        position: 3
                        type: INGREDIENTS
                        value:
                          id: 877
                          name: ''
                          title: apple and banana
                          servings: 1
                          imageType: jpg
                          ingredients:
                          - name: apple
                            unit: ''
                            amount: '1'
                            image: https://spoonacular.com/cdn/ingredients_100x100/apple.jpg
                          - name: banana
                            unit: ''
                            amount: '1'
                            image: https://spoonacular.com/cdn/ingredients_100x100/bananas.jpg
                    - nutritionSummary:
                        nutrients:
                        - name: Calories
                          amount: 180
                          unit: cal
                          percentDailyNeeds: 9
                        - name: Fat
                          amount: 6
                          unit: g
                          percentDailyNeeds: 9
                        - name: Carbohydrates
                          amount: 22
                          unit: g
                          percentDailyNeeds: 7
                        - name: Protein
                          amount: 10
                          unit: g
                          percentDailyNeeds: 20
                      nutritionSummaryBreakfast:
                        nutrients:
                        - name: Calories
                          amount: 180
                          unit: cal
                          percentDailyNeeds: 9
                        - name: Fat
                          amount: 6
                          unit: g
                          percentDailyNeeds: 9
                        - name: Carbohydrates
                          amount: 22
                          unit: g
                          percentDailyNeeds: 7
                        - name: Protein
                          amount: 10
                          unit: g
                          percentDailyNeeds: 20
                      nutritionSummaryLunch:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      nutritionSummaryDinner:
                        nutrients:
                        - name: Calories
                          amount: 0
                          unit: cal
                          percentDailyNeeds: 0
                        - name: Fat
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Carbohydrates
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                        - name: Protein
                          amount: 0
                          unit: g
                          percentDailyNeeds: 0
                      date: 1589328000
                      day: Wednesday
                      items:
                      - id: 1976492
                        slot: 1
                        position: 4
                        type: MENU_ITEM
                        value:
                          servings: 1
                          id: 378557
                          title: BBQ Steak Pizza, 9
                          image: https://images.spoonacular.com/file/wximages/378557-312x231.png
                          imageType: png
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: username
        description: The username.
        schema:
          type: string
          example: dsky
        required: true
        style: simple
        explode: false
        in: path
        example: dsky
      - name: start_date
        description: The start date of the meal planned week in the format yyyy-mm-dd.
        schema:
          type: string
          example: '2020-06-01'
        required: true
        style: simple
        explode: false
        in: path
        example: '2020-06-01'
      - $ref: '#/components/parameters/hash'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Get-Meal-Plan-Week
      summary: Get Meal Plan Week
      description: Retrieve a meal planned week for the given user. The username must be a spoonacular user and the hash must the the user's hash that can be found in his/her account.
      operationId: getMealPlanWeek
      deprecated: false
      tags:
      - Meal Planning
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /mealplanner/{username}/day/{date}:
    delete:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                type: object
              examples:
                ClearMealPlanDay200Example:
                  summary: Default clearMealPlanDay 200 response
                  x-microcks-default: true
                  value: {}
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: username
        description: The username.
        schema:
          type: string
          example: dsky
        required: true
        style: simple
        explode: false
        in: path
        example: dsky
      - name: date
        description: The date in the format yyyy-mm-dd.
        schema:
          type: string
          example: '2020-06-01'
        required: true
        style: simple
        explode: false
        in: path
        example: '2020-06-01'
      - $ref: '#/components/parameters/hash'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Clear-Meal-Plan-Day
      summary: Clear Meal Plan Day
      description: Delete all planned items from the user's meal plan for a specific day.
      operationId: clearMealPlanDay
      deprecated: false
      tags:
      - Meal Planning
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /mealplanner/{username}/items:
    post:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                description: ''
                type: object
              examples:
                example-1:
                  value:
                    date: 1589500800
                    slot: 1
                    position: 0
                    type: INGREDIENTS
                    value:
                      ingredients:
                      - name: 1 banana
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                date:
                  type: number
                slot:
                  type: integer
                position:
                  type: integer
                type:
                  type: string
                  minLength: 1
                value:
                  type: object
                  required:
                  - ingredients
                  properties:
                    ingredients:
                      type: array
                      uniqueItems: true
                      minItems: 0
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            minLength: 1
                        required:
                        - name
              required:
              - date
              - slot
              - position
              - type
              - value
            examples:
              example-1:
                value:
                  date: 1589500800
                  slot: 1
                  position: 0
                  type: INGREDIENTS
                  value:
                    ingredients:
                    - name: 1 banana
      parameters:
      - name: username
        description: The username.
        schema:
          type: string
          example: dsky
        required: true
        style: simple
        explode: false
        in: path
        example: dsky
      - $ref: '#/components/parameters/hash'
        example: example
      externalDocs:
        description: Read entire docs
        url: https://spoonacular.com/food-api/docs#Add-to-Meal-Plan
      summary: Add to Meal Plan
      description: Add an item to the user's meal plan.
      operationId: addToMealPlan
      deprecated: false
      tags:
      - Meal Planning
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /mealplanner/{username}/items/{id}:
    delete:
      responses:
        '200':
          description: Success
          headers: {}
          content:
            application/json:
              schema:
                type: object
    

# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spoonacular/refs/heads/main/openapi/spoonacular-meal-planning-api-openapi.yml