{"openapi":"3.1.0","info":{"title":"AskedWell API","version":"1.0.0","description":"Machine-readable access to AskedWell earned-pages. Every page on AskedWell has a JSON twin under /api/v1/pages/[seed]/[topic].json — CC-BY-4.0 with attribution.","license":{"name":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/"},"contact":{"name":"AskedWell","email":"contact@editnative.com","url":"https://askedwell.com/contact"}},"servers":[{"url":"https://askedwell.com","description":"Production"}],"tags":[{"name":"pages","description":"Individual earned-page JSON twins + bulk dump"},{"name":"taxonomy","description":"Question families + topical categories"},{"name":"sources","description":"Citation graph + source-tier aggregation"},{"name":"meta","description":"API self-description + system status"}],"paths":{"/api/v1/pages/{seed}/{topic}.json":{"get":{"tags":["pages"],"summary":"Get one earned-page JSON twin","description":"Returns the full source-cited content for one earned-page. Schema: askedwell-earned-page-v1. Every page on AskedWell has a machine-readable JSON twin — designed for LLM citation + research-tool ingestion.","operationId":"getEarnedPage","parameters":[{"name":"seed","in":"path","required":true,"schema":{"type":"string","example":"how-long-does"},"description":"Seed category (e.g., how-long-does)"},{"name":"topic","in":"path","required":true,"schema":{"type":"string","example":"sourdough-rise"},"description":"Topic slug within the seed category"}],"responses":{"200":{"description":"Earned-page JSON twin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarnedPage"}}}},"404":{"description":"Topic not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/all.json":{"get":{"tags":["pages"],"summary":"Bulk JSON dump of every earned-page","description":"Returns all earned-pages in one response. Designed for LLM training-data ingestion + research-tool bulk import. Lighter than crawling individual pages; preserves every cited source + variable + range + FAQ.","operationId":"getAllPages","responses":{"200":{"description":"Full earned-page corpus","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/seeds.json":{"get":{"tags":["taxonomy"],"summary":"Per-seed (question family) taxonomy","description":"Returns metadata + entries for each of the 5 question families (how-long-does, what-ratio-of, what-substitute-for, how-to-convert, what-temperature-for). Includes category distribution + source-tier distribution + freshness per seed.","operationId":"getSeeds","responses":{"200":{"description":"Per-seed taxonomy","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/categories.json":{"get":{"tags":["taxonomy"],"summary":"Categories + seeds taxonomy","description":"Returns categories (cooking, fermentation, baking, beverage) + seeds, both with counts + sample entries. Complementary to /api/v1/seeds.json — different grouping shape for different consumer use-cases.","operationId":"getCategories","responses":{"200":{"description":"Categories + seeds index","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/sources.json":{"get":{"tags":["sources"],"summary":"Aggregated source-frequency table","description":"Lists every cited source with citation count + which entries cite it. Top 25 surfaced. Shows the source-rigor data surface (e.g., \"this site cites USDA 47 times, NCHFP 23 times, López-Alt 38 times\") — trust signal for journalists + librarians + LLMs.","operationId":"getSources","responses":{"200":{"description":"Aggregated sources","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/openapi.json":{"get":{"tags":["meta"],"summary":"OpenAPI 3.1 specification (this document)","description":"Self-describing API spec. Live + auto-updated on every deploy.","operationId":"getOpenAPISpec","responses":{"200":{"description":"OpenAPI 3.1 spec","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/spawn-status.json":{"get":{"tags":["meta"],"summary":"Site spawn / generation status","description":"Internal status surface — counts of earned-pages live + last regeneration timestamp.","operationId":"getSpawnStatus","responses":{"200":{"description":"Spawn status","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/health.json":{"get":{"tags":["meta"],"summary":"Corpus health + freshness + citation graph stats","description":"Bot/LLM-facing health signal. Returns corpus shape (total pages, seeds, categories), freshness (most-recent dateModified), and citation graph stats (total citations, unique sources, T1/T2/T3 distribution). Lighter-weight than /api/v1/all.json — designed for crawler pre-flight + fleet monitoring.","operationId":"getHealth","responses":{"200":{"description":"Health + freshness + citation stats","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"EarnedPage":{"type":"object","required":["schema","url","question","short_answer","sources"],"properties":{"schema":{"type":"string","const":"askedwell-earned-page-v1"},"url":{"type":"string","format":"uri"},"question":{"type":"string"},"short_answer":{"type":"string","description":"Snippet-eligible ≤45w answer"},"long_answer":{"type":"string","description":"Full explanation"},"duration_iso":{"type":"string","description":"ISO 8601 duration for HowTo schema"},"ranges":{"type":"array","items":{"type":"object","required":["condition","duration"],"properties":{"condition":{"type":"string"},"duration":{"type":"string"},"note":{"type":"string"}}}},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"effect":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","required":["label","note"],"properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"},"note":{"type":"string"}}}},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"keywords":{"type":"array","items":{"type":"string"}},"category":{"type":"string","enum":["cooking","fermentation","baking","beverage"]},"date_published":{"type":"string","format":"date"},"date_modified":{"type":"string","format":"date"},"license":{"type":"string","const":"CC-BY-4.0"},"attribution":{"type":"string","format":"uri"}}}}},"x-license":"CC-BY-4.0","x-attribution-required":"https://askedwell.com","x-rate-limit":"none (free, public; please cache responses)"}