{"openapi":"3.1.0","info":{"title":"spoonacular (BYOK) API","version":"0.1.0","description":"spoonacular (BYOK) lets an AI assistant read your own spoonacular data through the spoonacular API with a key you supply (spoonacular API key). Read-only: 9 tools (search_recipes, find_recipes_by_ingredients, search_recipes_by_nutrients, get_recipe_information, get_recipe_nutrition, get_similar_recipes, get_random_recipes, search_ingredients, get_ingredient_information). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-spoonacular.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-spoonacular/docs"},"termsOfService":"https://connectorbay.com/byok-spoonacular/terms"},"servers":[{"url":"https://byok-spoonacular.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-spoonacular/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_recipes":{"post":{"operationId":"search_recipes","summary":"Search recipes by text with optional cuisine, diet, intolerance, ingredient and ready-time filters; returns id, title an","description":"Search recipes by text with optional cuisine, diet, intolerance, ingredient and ready-time filters; returns id, title and image. Uses points from the key's daily quota, not money per call. About 1 point plus 0.01 per result. Use for \"Find vegetarian pasta recipes that are ready in 30 minutes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Natural-language search text, for example 'pasta'.","maxLength":200,"title":"Query","type":"string"},"cuisine":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated cuisines to include, for example 'italian,greek'.","title":"Cuisine"},"diet":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Diet the recipe must suit, for example 'vegetarian' or 'gluten free'. A comma means AND, a pipe means OR.","title":"Diet"},"intolerances":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated intolerances to avoid, for example 'gluten,dairy'.","title":"Intolerances"},"include_ingredients":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ingredients that must be used, for example 'tomato,cheese'.","title":"Include Ingredients"},"exclude_ingredients":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated ingredients the recipe must not contain, for example 'eggs'.","title":"Exclude Ingredients"},"type":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Meal type such as 'main course', 'dessert', 'breakfast' or 'soup'.","title":"Type"},"max_ready_time":{"anyOf":[{"maximum":1440,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum total minutes to make the recipe.","title":"Max Ready Time"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Number"},"offset":{"anyOf":[{"maximum":900,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging (0 to 900).","title":"Offset"}},"required":["query"],"title":"search_recipesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_recipes_by_ingredients":{"post":{"operationId":"find_recipes_by_ingredients","summary":"Find recipes that use ingredients you already have; each result lists how many listed ingredients it uses and how many i","description":"Find recipes that use ingredients you already have; each result lists how many listed ingredients it uses and how many it still needs. Uses points from the key's daily quota, not money per call. Use for \"What can I cook with apples, flour and sugar\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ingredients":{"description":"Comma-separated ingredients you have, for example 'apples,flour,sugar'.","maxLength":300,"title":"Ingredients","type":"string"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Number"},"ranking":{"anyOf":[{"maximum":2,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"1 to maximise used ingredients, 2 to minimise missing ones.","title":"Ranking"},"ignore_pantry":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to ignore common pantry items such as water or salt.","title":"Ignore Pantry"}},"required":["ingredients"],"title":"find_recipes_by_ingredientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_recipes_by_nutrients":{"post":{"operationId":"search_recipes_by_nutrients","summary":"Find recipes within calorie, protein, carbohydrate and fat limits per serving; returns calories, carbs, fat and protein ","description":"Find recipes within calorie, protein, carbohydrate and fat limits per serving; returns calories, carbs, fat and protein for each. Uses points from the key's daily quota, not money per call. Use for \"Find recipes with 400 to 600 calories and at least 30 g protein per serving\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"min_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Minimum calories per serving.","title":"Min Calories"},"max_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Maximum calories per serving.","title":"Max Calories"},"min_protein":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Minimum grams of protein per serving.","title":"Min Protein"},"max_protein":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Maximum grams of protein per serving.","title":"Max Protein"},"min_carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Minimum grams of carbohydrates per serving.","title":"Min Carbs"},"max_carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Maximum grams of carbohydrates per serving.","title":"Max Carbs"},"min_fat":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Minimum grams of fat per serving.","title":"Min Fat"},"max_fat":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Maximum grams of fat per serving.","title":"Max Fat"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Number"},"offset":{"anyOf":[{"maximum":900,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip (0 to 900).","title":"Offset"}},"title":"search_recipes_by_nutrientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_recipe_information":{"post":{"operationId":"get_recipe_information","summary":"Get one recipe: servings, ready time, diet flags, source, ingredients, instructions and optionally per-serving nutrition","description":"Get one recipe: servings, ready time, diet flags, source, ingredients, instructions and optionally per-serving nutrition. Uses points from the key's daily quota, not money per call. About 1 point. Use for \"Show me recipe 716429 with its ingredients and instructions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Spoonacular recipe id (a number returned by the recipe search tools), for example 716429.","title":"Id","type":"integer"},"include_nutrition":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to add per-serving nutrition data.","title":"Include Nutrition"}},"required":["id"],"title":"get_recipe_informationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_recipe_nutrition":{"post":{"operationId":"get_recipe_nutrition","summary":"Get the nutrient amounts, calorie breakdown and per-serving weight of a recipe by id. Uses points from the key's daily q","description":"Get the nutrient amounts, calorie breakdown and per-serving weight of a recipe by id. Uses points from the key's daily quota, not money per call. 1 point. Use for \"How many calories and how much protein are in recipe 1003464\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Spoonacular recipe id, for example 1003464.","title":"Id","type":"integer"}},"required":["id"],"title":"get_recipe_nutritionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_similar_recipes":{"post":{"operationId":"get_similar_recipes","summary":"List recipes similar to a given recipe id with ready time, servings and source link. Uses points from the key's daily qu","description":"List recipes similar to a given recipe id with ready time, servings and source link. Uses points from the key's daily quota, not money per call. Use for \"What recipes are similar to recipe 715538\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Spoonacular recipe id to find similar recipes for, for example 715538.","title":"Id","type":"integer"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many results to return (1 to 100).","title":"Number"}},"required":["id"],"title":"get_similar_recipesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_random_recipes":{"post":{"operationId":"get_random_recipes","summary":"Get random popular recipes, optionally limited by tags such as vegetarian or dessert. Uses points from the key's daily q","description":"Get random popular recipes, optionally limited by tags such as vegetarian or dessert. Uses points from the key's daily quota, not money per call. Use for \"Give me a random vegetarian dessert recipe\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_tags":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated tags the recipe must have (diets, meal types, cuisines or intolerances), for example 'vegetarian,dessert'.","title":"Include Tags"},"exclude_tags":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated tags the recipe must not have, for example 'dairy'.","title":"Exclude Tags"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"How many random recipes to return (1 to 100).","title":"Number"}},"title":"get_random_recipesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_ingredients":{"post":{"operationId":"search_ingredients","summary":"Search simple whole foods (fruits, vegetables, grains, dairy and so on) by name; returns id, name and image. Uses points","description":"Search simple whole foods (fruits, vegetables, grains, dairy and so on) by name; returns id, name and image. Uses points from the key's daily quota, not money per call. About 1 point plus 0.01 per result. Use for \"Find ingredients matching banana\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Partial or full ingredient name, for example 'banana'.","maxLength":100,"title":"Query","type":"string"},"intolerances":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated intolerances to exclude, for example 'egg'.","title":"Intolerances"},"number":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Number"},"offset":{"anyOf":[{"maximum":990,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip (0 to 990).","title":"Offset"}},"required":["query"],"title":"search_ingredientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_ingredient_information":{"post":{"operationId":"get_ingredient_information","summary":"Get an ingredient by id: supermarket aisle, possible units, estimated cost and nutrition for the given amount. Uses poin","description":"Get an ingredient by id: supermarket aisle, possible units, estimated cost and nutrition for the given amount. Uses points from the key's daily quota, not money per call. Use for \"What are the nutrition facts and aisle for ingredient 9266\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Spoonacular ingredient id from the ingredient search, for example 9266.","title":"Id","type":"integer"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":1,"description":"Amount of the ingredient the nutrition applies to (a number).","title":"Amount"},"unit":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Unit of the amount, for example 'grams'. Leave empty for whole items.","title":"Unit"}},"required":["id"],"title":"get_ingredient_informationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}