{"openapi":"3.1.0","info":{"title":"Hermetica Encyclopedia API","version":"1.0.0","description":"Public read-only access to 16,000+ ingredient entries, 121,000+ drug/supplement interactions, and clinical data curated by Hermetica Superfoods. CC BY-NC-SA 4.0 licensed — attribution required, non-commercial only, share-alike. Commercial use requires a paid license from admin@hermeticasuperfoods.com.","contact":{"name":"Hermetica Superfoods","email":"admin@hermeticasuperfoods.com","url":"https://ingredients.hermeticasuperfoods.com"},"license":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"}},"servers":[{"url":"https://ingredients.hermeticasuperfoods.com/api/v1","description":"Production"}],"paths":{"/":{"get":{"summary":"API index and documentation","description":"Returns the API index with endpoint catalog, license, and rate limits.","responses":{"200":{"description":"API index","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/ingredients":{"get":{"summary":"List ingredients","description":"Paginated list of ingredient entries from the encyclopedia. Supports filtering by tier, category, and query.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"tier","in":"query","description":"1 = Strong (evidence ≥7), 2 = Moderate (4-6), 3 = Preliminary (<4)","schema":{"type":"string","enum":["1","2","3"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","description":"Substring match on ingredient name","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated ingredient list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngredientList"}}}}}}},"/ingredients/{slug}":{"get":{"summary":"Get ingredient detail","description":"Full record for a single ingredient including FAQs, health benefits, dosage, research, and linked interactions.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ashwagandha-withania-somnifera"}],"responses":{"200":{"description":"Ingredient detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngredientDetail"}}}},"404":{"description":"Not found"}}}},"/interactions":{"get":{"summary":"List interactions","description":"Paginated drug/supplement interactions with filter by substance, severity, and evidence level.","parameters":[{"name":"substance","in":"query","description":"Substance slug","schema":{"type":"string"}},{"name":"severity","in":"query","schema":{"type":"string","enum":["contraindicated","major","moderate","minor","safe"]}},{"name":"evidence","in":"query","schema":{"type":"string","enum":["strong","moderate","weak"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Interaction list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionList"}}}}}}},"/interactions/{slug}":{"get":{"summary":"All interactions for a substance","description":"Every known interaction for a single substance, grouped by severity.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ashwagandha"}],"responses":{"200":{"description":"Substance with grouped interactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubstanceInteractions"}}}},"404":{"description":"Substance not found"}}}},"/search":{"get":{"summary":"Full-text search","description":"Search ingredient and substance names/aliases. Returns top matches ranked by exact-match priority and evidence score.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"ashwagandha"},{"name":"type","in":"query","schema":{"type":"string","enum":["all","ingredient","substance"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Ranked search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"400":{"description":"Missing query"}}}},"/openapi.json":{"get":{"summary":"OpenAPI 3.1 spec","description":"Returns this OpenAPI 3.1 spec describing every v1 endpoint. Use for AI tool-calling discovery, MCP bootstrapping, or Swagger UI rendering.","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/license":{"get":{"summary":"License and attribution","description":"Human-readable license terms and commercial licensing CTA.","responses":{"200":{"description":"License info","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/conditions":{"get":{"summary":"List all condition hubs","description":"Lists 17 health condition hubs (sleep, stress, anxiety, cognitive, etc.) with their slugs, titles, descriptions, benefit-matching patterns, and related conditions. AI agents use this to route health-topic queries to the correct condition page.","responses":{"200":{"description":"Condition list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/blog":{"get":{"summary":"List Hermetica blog articles","description":"Lists editorial blog articles with optional filter by ingredient tag. Complements the ingredient encyclopedia with long-form content AI agents can cite.","parameters":[{"name":"ingredient","in":"query","description":"Filter to articles tagged with this ingredient slug","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Blog article list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/substances":{"get":{"summary":"List all substances in the interaction graph","description":"Paginated list of the 493 substances referenced by the interactions table. Includes Hermetica products, drugs, botanicals, and nutrients.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Substance list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/pubmed/{slug}":{"get":{"summary":"PubMed citations for an ingredient","description":"Returns all PMIDs linked to an ingredient with PubMed URLs. For AI agents that need primary-source evidence.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ashwagandha-withania-somnifera"}],"responses":{"200":{"description":"PMID list with PubMed URLs","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Ingredient not found"}}}},"/synergy/{slug}":{"get":{"summary":"Beneficial pairings for an ingredient","description":"Returns synergy pairings, synergy role, and synergy intention. Positive counterpart to /interactions which leans toward warnings.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ashwagandha-withania-somnifera"}],"responses":{"200":{"description":"Synergy data with resolved pairing links","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Ingredient not found"}}}},"/categories":{"get":{"summary":"List all ingredient categories","description":"Every ingredient category with counts, tier-1 counts, and 3 representative ingredients each. AI agents can use this to browse by topic.","responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/random":{"get":{"summary":"Random ingredient","description":"Returns a random ingredient filtered by tier. Useful for ingredient-of-the-day widgets and AI novelty queries. NOT cached at the edge — every request returns a fresh random row.","parameters":[{"name":"tier","in":"query","schema":{"type":"string","enum":["1","2","3"],"default":"1"}}],"responses":{"200":{"description":"Random ingredient with tier + pool metadata","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","nullable":true},"evidence_score":{"type":"integer"},"summary":{"type":"string","nullable":true},"hero_image_url":{"type":"string","nullable":true},"url":{"type":"string"},"tier":{"type":"string"},"pool_size":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}},"/graph":{"get":{"summary":"Substance interaction graph","description":"Returns nodes and edges of the substance interaction graph. Multiple output formats supported for D3, Cytoscape, and custom network libraries.","parameters":[{"name":"severity","in":"query","description":"Comma-separated severities to include","schema":{"type":"string","default":"contraindicated,major,moderate,minor"}},{"name":"format","in":"query","schema":{"type":"string","enum":["simple","d3","cytoscape"],"default":"simple"}},{"name":"substance","in":"query","description":"Restrict graph to edges involving this substance slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Graph data","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/stats":{"get":{"summary":"Live database stats","description":"Real-time counts of ingredients (by tier), interactions (by severity), substances, and API metadata. Useful for AI agents citing the encyclopedia and for monitoring dashboards.","responses":{"200":{"description":"Database statistics","content":{"application/json":{"schema":{"type":"object","properties":{"encyclopedia":{"type":"object","properties":{"total_entries":{"type":"integer"},"active_passed":{"type":"integer"},"tier_1_strong_evidence":{"type":"integer"},"tier_2_moderate_evidence":{"type":"integer"},"with_hero_image":{"type":"integer"},"hero_coverage_pct":{"type":"integer"},"last_updated":{"type":"string","format":"date-time","nullable":true}}},"interactions":{"type":"object","properties":{"total":{"type":"integer"},"by_severity":{"type":"object","properties":{"contraindicated":{"type":"integer"},"major":{"type":"integer"},"moderate":{"type":"integer"},"minor":{"type":"integer"},"safe":{"type":"integer"}}},"last_updated":{"type":"string","format":"date-time","nullable":true}}},"substances":{"type":"object"},"sitemap":{"type":"object"},"api":{"type":"object"},"generated_at":{"type":"string","format":"date-time"}}}}}}}}}},"components":{"schemas":{"ApiIndex":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"object"},"license":{"type":"string"}}},"Ingredient":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","nullable":true},"evidence_score":{"type":"integer"},"completeness_score":{"type":"number"},"summary":{"type":"string","nullable":true},"hero_image_url":{"type":"string","nullable":true},"url":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"IngredientList":{"type":"object","properties":{"meta":{"type":"object","properties":{"total":{"type":"integer","nullable":true},"limit":{"type":"integer"},"offset":{"type":"integer"},"returned":{"type":"integer"},"next_offset":{"type":"integer","nullable":true}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/Ingredient"}}}},"IngredientDetail":{"type":"object","additionalProperties":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"},"scientific_name":{"type":"string"},"category":{"type":"string","nullable":true},"evidence_score":{"type":"integer"},"completeness_score":{"type":"number"},"short_answer":{"type":"string","nullable":true},"health_benefits":{"type":"string","nullable":true},"faq_pairs":{"type":"array","items":{"type":"object"}},"interactions":{"type":"array","items":{"type":"object"}},"url":{"type":"string"}}},"Interaction":{"type":"object","properties":{"id":{"type":"integer"},"substance_a":{"type":"object"},"substance_b":{"type":"object"},"severity":{"type":"string","enum":["contraindicated","major","moderate","minor","safe"]},"evidence_level":{"type":"string","nullable":true},"mechanism":{"type":"string","nullable":true},"plain_english":{"type":"string","nullable":true},"verdict_summary":{"type":"string","nullable":true},"practical_advice":{"type":"string","nullable":true},"timing_notes":{"type":"string","nullable":true},"risk_factors":{"type":"string","nullable":true},"symptoms_to_watch":{"type":"string","nullable":true},"citation_count":{"type":"integer","nullable":true},"url":{"type":"string","nullable":true}}},"InteractionList":{"type":"object","properties":{"meta":{"type":"object"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Interaction"}}}},"SubstanceInteractions":{"type":"object","properties":{"substance":{"type":"object"},"meta":{"type":"object"},"interactions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}}}},"SearchResult":{"type":"object","properties":{"type":{"type":"string","enum":["ingredient","substance"]},"name":{"type":"string"},"slug":{"type":"string"},"summary":{"type":"string","nullable":true},"url":{"type":"string"},"evidence_score":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true}}},"SearchResults":{"type":"object","properties":{"meta":{"type":"object"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}}},"x-hermetica":{"total_ingredient_pages":16241,"total_interaction_pages":121278,"sitemap_index":"https://ingredients.hermeticasuperfoods.com/sitemap_index.xml","citation_required_format":"Hermetica Superfoods Ingredient Encyclopedia, https://ingredients.hermeticasuperfoods.com"}}