{"openapi":"3.1.0","info":{"title":"Food Tales Knowledge API","description":"Canonical Dish/Region/Family/Recipe/Ingredient projections (semantic layer). A Dish (DSH-…) is the cultural entity; a Recipe (RCP-…) is a cookable variant. Public recipe lists default to published only (public_only=true). Credits are tiered by action (basic read/search = 1; semantic/multi-filter = 3; higher for analysis/AI when those endpoints ship). No-sign-up demo: /demo/ · Trust: /v1/demo/trust · Signup: https://foodtales.ai/signup · Recipe API: https://api.foodtales.ai/","version":"0.8.0"},"paths":{"/":{"get":{"summary":"Root","description":"Browser landing (foodtales.ai chrome) or JSON welcome for API clients.\n\nBrowsers send ``Accept: text/html`` → branded overview (same nav as foodtales.ai).\ncurl / default ``*/*`` → JSON welcome (same DX as api.foodtales.ai/).","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Healthz","operationId":"healthz_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Healthz Health Get"}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Healthz Healthz Get"}}}}}}},"/coverage/":{"get":{"summary":"Coverage Dashboard","description":"Interactive dish coverage dashboard (continent / cuisine / subcuisine).","operationId":"coverage_dashboard_coverage__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/coverage":{"get":{"summary":"Coverage Dashboard","description":"Interactive dish coverage dashboard (continent / cuisine / subcuisine).","operationId":"coverage_dashboard_coverage_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/demo/":{"get":{"summary":"Cuisine Demo","description":"No-sign-up cuisine browse demo (hierarchy → dishes → siblings).","operationId":"cuisine_demo_demo__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/demo":{"get":{"summary":"Cuisine Demo","description":"No-sign-up cuisine browse demo (hierarchy → dishes → siblings).","operationId":"cuisine_demo_demo_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/demo/trust":{"get":{"summary":"Demo Trust","description":"Public trust payload: dish/recipe model, rights, credits, roadmap, geo counts.","operationId":"demo_trust_v1_demo_trust_get","parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass short regions cache","default":false,"title":"Refresh"},"description":"Bypass short regions cache"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/demo/browse":{"get":{"summary":"Demo Browse","description":"Public cuisine hierarchy walk (summary fields only; no API key).","operationId":"demo_browse_v1_demo_browse_get","parameters":[{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continent"}},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},{"name":"state_region","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Region"}},{"name":"subcuisine","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subcuisine"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":24,"title":"Limit"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass short regions cache","default":false,"title":"Refresh"},"description":"Bypass short regions cache"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/demo/dishes/{dish_ref}/siblings":{"get":{"summary":"Demo Siblings","description":"Public family siblings for a dish (regional variants; no API key).","operationId":"demo_siblings_v1_demo_dishes__dish_ref__siblings_get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":12,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/coverage/dishes":{"get":{"summary":"Dish Coverage","description":"Dish counts and avg recipes/dish by geography, filterable by meal type.","operationId":"dish_coverage_v1_coverage_dishes_get","parameters":[{"name":"group_by","in":"query","required":false,"schema":{"type":"string","description":"Rollup level: continent | cuisine | subcuisine","default":"subcuisine","title":"Group By"},"description":"Rollup level: continent | cuisine | subcuisine"},{"name":"continent","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continent"}},{"name":"cuisine","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cuisine (= country)","title":"Cuisine"},"description":"Cuisine (= country)"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for cuisine","title":"Country"},"description":"Alias for cuisine"},{"name":"subcuisine","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subcuisine"}},{"name":"meal_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated meal buckets: main,appetizer,dessert,other,all","title":"Meal Type"},"description":"Comma-separated meal buckets: main,appetizer,dessert,other,all"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"dish_count|avg_recipe_count|recipe_count|label","default":"dish_count","title":"Sort"},"description":"dish_count|avg_recipe_count|recipe_count|label"},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"asc|desc","default":"asc","title":"Order"},"description":"asc|desc"},{"name":"lightest_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"default":25,"title":"Lightest Limit"}},{"name":"lightest_metric","in":"query","required":false,"schema":{"type":"string","description":"dish_count|avg_recipe_count","default":"dish_count","title":"Lightest Metric"},"description":"dish_count|avg_recipe_count"},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Bypass short server cache","default":false,"title":"Refresh"},"description":"Bypass short server cache"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"get":{"summary":"Search","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search query (dish name)","title":"Q"},"description":"Search query (dish name)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page (licensing mode)","title":"Cursor"},"description":"Opaque cursor from a previous page (licensing mode)"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","description":"lexical (default) | hybrid (RRF lexical+vector) | vector","default":"lexical","title":"Mode"},"description":"lexical (default) | hybrid (RRF lexical+vector) | vector"},{"name":"model","in":"query","required":false,"schema":{"type":"string","description":"Embedding model for mode=hybrid|vector","default":"text-embedding-3-small","title":"Model"},"description":"Embedding model for mode=hybrid|vector"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/similar/dishes/{dish_ref}":{"get":{"summary":"Similar Dishes","description":"Cosine nearest-neighbor dishes for a seed dish (requires dish_embeddings).","operationId":"similar_dishes_v1_similar_dishes__dish_ref__get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"model","in":"query","required":false,"schema":{"type":"string","description":"Embedding model id","default":"text-embedding-3-small","title":"Model"},"description":"Embedding model id"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/similar/recipes/{recipe_ref}":{"get":{"summary":"Similar Recipes","description":"Cosine nearest-neighbor recipes for a seed recipe (requires recipe_embeddings).\n\nrecipe_ref may be the bigint id or stable sku (e.g. RCP-B786).","operationId":"similar_recipes_v1_similar_recipes__recipe_ref__get","parameters":[{"name":"recipe_ref","in":"path","required":true,"schema":{"type":"string","title":"Recipe Ref"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"model","in":"query","required":false,"schema":{"type":"string","description":"Embedding model id","default":"text-embedding-3-small","title":"Model"},"description":"Embedding model id"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dishes/{dish_ref}":{"get":{"summary":"Get Dish","description":"Fetch a dish by canonical id (numeric) or stable sku (e.g. DSH-BB17).","operationId":"get_dish_v1_dishes__dish_ref__get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dishes/{dish_ref}/relationships":{"get":{"summary":"Get Relationships","operationId":"get_relationships_v1_dishes__dish_ref__relationships_get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"public_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only count ingredients from public recipes for CONTAINS edges","default":true,"title":"Public Only"},"description":"Only count ingredients from public recipes for CONTAINS edges"},{"name":"ingredient_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"Max CONTAINS ingredient edges to include","default":50,"title":"Ingredient Limit"},"description":"Max CONTAINS ingredient edges to include"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dishes/{dish_ref}/ingredients":{"get":{"summary":"Get Dish Ingredients","description":"Dish-level ingredient summary (CONTAINS rollup over recipe_ingredients).","operationId":"get_dish_ingredients_v1_dishes__dish_ref__ingredients_get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"public_only","in":"query","required":false,"schema":{"type":"boolean","description":"Aggregate only from public recipes (§27 policy)","default":true,"title":"Public Only"},"description":"Aggregate only from public recipes (§27 policy)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Max distinct ingredients","default":100,"title":"Limit"},"description":"Max distinct ingredients"},{"name":"recipe_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Max recipes to scan for the rollup","default":50,"title":"Recipe Limit"},"description":"Max recipes to scan for the rollup"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/dishes/{dish_ref}/recipes":{"get":{"summary":"Get Recipes","operationId":"get_recipes_v1_dishes__dish_ref__recipes_get","parameters":[{"name":"dish_ref","in":"path","required":true,"schema":{"type":"string","title":"Dish Ref"}},{"name":"public_only","in":"query","required":false,"schema":{"type":"boolean","description":"Default true: return published recipes only (§27). Set false only for authenticated ops that need drafts.","default":true,"title":"Public Only"},"description":"Default true: return published recipes only (§27). Set false only for authenticated ops that need drafts."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"include_ingredients","in":"query","required":false,"schema":{"type":"boolean","description":"Attach normalized recipe_ingredients lines to each recipe","default":false,"title":"Include Ingredients"},"description":"Attach normalized recipe_ingredients lines to each recipe"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ingredients":{"get":{"summary":"Search Ingredients","operationId":"search_ingredients_v1_ingredients_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Ingredient name query","title":"Q"},"description":"Ingredient name query"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ingredients/{ingredient_id}":{"get":{"summary":"Get Ingredient","operationId":"get_ingredient_v1_ingredients__ingredient_id__get","parameters":[{"name":"ingredient_id","in":"path","required":true,"schema":{"type":"string","title":"Ingredient Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ingredients/{ingredient_id}/recipes":{"get":{"summary":"Get Ingredient Recipes","operationId":"get_ingredient_recipes_v1_ingredients__ingredient_id__recipes_get","parameters":[{"name":"ingredient_id","in":"path","required":true,"schema":{"type":"string","title":"Ingredient Id"}},{"name":"public_only","in":"query","required":false,"schema":{"type":"boolean","description":"Default true: only published recipes (§27 public surface)","default":true,"title":"Public Only"},"description":"Default true: only published recipes (§27 public surface)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-FT-Package-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ft-Package-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}