{"openapi":"3.1.0","info":{"title":"AI Recipes for Charities API","version":"1.0.0","description":"Read-only access to a curated collection of practical AI and machine learning recipes for UK charities, and the learning pathways built from them. No authentication is required and all responses are CORS-open.","contact":{"name":"Make Sense of It","url":"https://make-sense-of-it.com"},"license":{"name":"See site terms","url":"https://www.airecipesforcharities.com/terms"}},"servers":[{"url":"https://www.airecipesforcharities.com/api/v1","description":"This deployment"}],"tags":[{"name":"Recipes","description":"Individual AI recipes"},{"name":"Pathways","description":"Ordered sequences of recipes"},{"name":"Meta","description":"Filter vocabulary and collection statistics"}],"paths":{"/recipes":{"get":{"tags":["Recipes"],"summary":"List recipes","description":"Filter, search, sort and page through published recipes. Filters combine with AND across parameters and OR within a single parameter, except tag, which requires every listed tag to be present.","operationId":"listRecipes","parameters":[{"name":"category","in":"query","description":"Charity function area. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["data-analysis","service-delivery","fundraising","operations","impact-measurement","communications","compliance"]}},"style":"form","explode":true},{"name":"technique","in":"query","description":"AI or ML technique used. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["llm","classical-ml","traditional-stats","tool-use","agents","optimisation","neurosymbolic","vision","edge-ai"]}},"style":"form","explode":true},{"name":"complexity","in":"query","description":"Skill level required. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["beginner","intermediate","advanced","expert"]}},"style":"form","explode":true},{"name":"maturity","in":"query","description":"How established the approach is. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["experimental","emerging","proven","commoditising"]}},"style":"form","explode":true},{"name":"time","in":"query","description":"Time to implement. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["hours","days","weeks","months"]}},"style":"form","explode":true},{"name":"orgSize","in":"query","description":"Organisation size the recipe suits. Repeat the parameter or comma-separate values to match any of them.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["micro","small","medium","large"]}},"style":"form","explode":true},{"name":"tag","in":"query","description":"Free-form tag. Repeat or comma-separate to require all of them. Case insensitive.","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"q","in":"query","description":"Case-insensitive substring search across title, problem, solution and tags.","required":false,"schema":{"type":"string","maxLength":200}},{"name":"sort","in":"query","description":"Field to sort by. Recipes missing the sort value are placed last in either direction.","required":false,"schema":{"type":"string","enum":["dateAdded","title","utilityScore","complexity","time"],"default":"dateAdded"}},{"name":"order","in":"query","description":"Sort direction. Defaults to asc for title and desc for everything else.","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"fields","in":"query","description":"summary returns list-view fields. full returns complete recipes including steps, tools, code and resources, and lowers the maximum limit to 50.","required":false,"schema":{"type":"string","enum":["summary","full"],"default":"summary"}},{"name":"limit","in":"query","description":"Results per page.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Results to skip.","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of recipes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipeList"}}}},"400":{"description":"One or more query parameters were rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recipes/{slug}":{"get":{"tags":["Recipes"],"summary":"Get one recipe","description":"Returns a single published recipe in full.","operationId":"getRecipe","parameters":[{"name":"slug","in":"path","required":true,"description":"URL slug of the recipe.","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"example":"analyse-feedback-at-scale"},{"name":"include","in":"query","required":false,"description":"Set to pathways to also return the pathways featuring this recipe.","schema":{"type":"array","items":{"type":"string","enum":["pathways"]}},"style":"form","explode":true}],"responses":{"200":{"description":"The recipe","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Recipe"},"included":{"type":"object","description":"Present only when include=pathways was requested.","properties":{"pathways":{"type":"array","items":{"$ref":"#/components/schemas/PathwaySummary"}}}}},"required":["data"]}}}},"400":{"description":"The slug was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No published recipe has that slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pathways":{"get":{"tags":["Pathways"],"summary":"List pathways","description":"All published learning pathways as summaries. Unpaginated.","operationId":"listPathways","responses":{"200":{"description":"All pathways","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PathwaySummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"count":{"type":"integer"}}}},"required":["data"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pathways/{slug}":{"get":{"tags":["Pathways"],"summary":"Get one pathway","description":"Returns a pathway with all of its stages and the recipes in each.","operationId":"getPathway","parameters":[{"name":"slug","in":"path","required":true,"description":"URL slug of the pathway.","schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"The pathway","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pathway"}},"required":["data"]}}}},"400":{"description":"The slug was malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No published pathway has that slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/meta":{"get":{"tags":["Meta"],"summary":"Filter vocabulary and counts","description":"Every filterable value with the number of recipes carrying it, plus the most common tags. Values with no matches are included so filter controls stay stable.","operationId":"getMeta","responses":{"200":{"description":"Facet counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meta"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"code":{"type":"string","enum":["VALIDATION_FAILED","NOT_FOUND","RATE_LIMITED","INTERNAL_ERROR"]},"details":{"type":"array","description":"Present on VALIDATION_FAILED. One entry per rejected parameter.","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","code"]},"Facet":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer"}},"required":["value","count"]},"Meta":{"type":"object","properties":{"data":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"techniques":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"complexity":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"maturity":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"timeToImplement":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"organisationSize":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Facet"}}}},"meta":{"type":"object","properties":{"totalRecipes":{"type":"integer"},"totalTags":{"type":"integer"},"tagsShown":{"type":"integer"},"lastUpdated":{"type":["string","null"],"format":"date-time"}}}},"required":["data"]},"RecipeList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecipeSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Recipes matching the filters."},"count":{"type":"integer","description":"Recipes in this page."},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"},"fields":{"type":"string","enum":["summary","full"]},"sort":{"type":"string","enum":["dateAdded","title","utilityScore","complexity","time"]},"order":{"type":"string","enum":["asc","desc"]},"lastUpdated":{"type":["string","null"],"format":"date-time"}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"next":{"type":["string","null"],"format":"uri"},"prev":{"type":["string","null"],"format":"uri"}}}},"required":["data","meta","links"]},"RecipeImage":{"type":"object","description":"Illustration sourced from Unsplash. Attribution is required on display.","properties":{"url":{"type":"string","format":"uri"},"attribution":{"type":"object","properties":{"photographerName":{"type":"string"},"photographerUrl":{"type":"string","format":"uri"},"unsplashUrl":{"type":"string","format":"uri"}}},"unsplashId":{"type":"string"}}},"RecipeSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"problem":{"type":"string","description":"The job to be done."},"solution":{"type":"string","description":"The high-level approach."},"category":{"type":"string","enum":["data-analysis","service-delivery","fundraising","operations","impact-measurement","communications","compliance"]},"techniques":{"type":"array","items":{"type":"string","enum":["llm","classical-ml","traditional-stats","tool-use","agents","optimisation","neurosymbolic","vision","edge-ai"]}},"complexity":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"maturity":{"type":"string","enum":["experimental","emerging","proven","commoditising"]},"timeToImplement":{"type":"string","enum":["hours","days","weeks","months"]},"organisationSize":{"type":"array","items":{"type":"string","enum":["micro","small","medium","large"]}},"tags":{"type":"array","items":{"type":"string"}},"utilityScore":{"type":"integer","minimum":0,"maximum":100,"description":"Editorial usefulness score. Absent on unscored recipes."},"dateAdded":{"type":"string","format":"date","description":"YYYY-MM-DD."},"image":{"$ref":"#/components/schemas/RecipeImage"}},"required":["id","slug","title","category","complexity","maturity"]},"Tool":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["service","library","platform","hardware"]},"url":{"type":"string","format":"uri"},"cost":{"type":"string","enum":["free","freemium","paid"]},"openSource":{"type":"boolean"},"skillLevel":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"alternatives":{"type":"array","items":{"type":"string"}}}},"Step":{"type":"object","properties":{"order":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"estimatedTime":{"type":"string"},"optional":{"type":"boolean"}}},"CodeExample":{"type":"object","properties":{"language":{"type":"string"},"title":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"}}},"Resource":{"type":"object","properties":{"type":{"type":"string","enum":["documentation","tutorial","paper","video","tool"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}},"Recipe":{"allOf":[{"$ref":"#/components/schemas/RecipeSummary"},{"type":"object","properties":{"output":{"type":"string","description":"What you end up with."},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"prerequisites":{"type":"array","items":{"type":"string"}},"costProfile":{"type":"object","properties":{"setup":{"type":"string","enum":["free","low","medium","high"]},"ongoing":{"type":"string","enum":["free","low","medium","high"]},"trend":{"type":"string","enum":["decreasing","stable","increasing"]},"notes":{"type":"string"}}},"whenToUse":{"type":"array","items":{"type":"string"}},"whenNotToUse":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"type":"string"},"description":"Recipe ids of related approaches."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/Step"}},"exampleCode":{"type":"array","items":{"$ref":"#/components/schemas/CodeExample"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}},"targetAudience":{"type":"array","items":{"type":"string","enum":["ceo-trustees","operations-manager","program-delivery","fundraising","comms-marketing","finance","it-technical","volunteer-coordinator","data-analyst"]}},"author":{"type":"string"},"lastUpdated":{"type":"string","format":"date","description":"YYYY-MM-DD."}}}]},"PathwaySummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"stageCount":{"type":"integer"},"totalRecipes":{"type":"integer"},"complexity":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"estimatedTime":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"},"stageName":{"type":"string","description":"Only present under included.pathways, naming the stage that holds the recipe."}}},"PathwayStage":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"order":{"type":"integer"},"outcomes":{"type":"array","items":{"type":"string"}},"estimatedTime":{"type":"string"},"recipes":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"References a recipe slug."},"optional":{"type":"boolean"},"notes":{"type":"string"}},"required":["slug"]}}}},"Pathway":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"longDescription":{"type":"string"},"targetAudience":{"type":"array","items":{"type":"string","enum":["ceo-trustees","operations-manager","program-delivery","fundraising","comms-marketing","finance","it-technical","volunteer-coordinator","data-analyst"]}},"complexity":{"type":"string","enum":["beginner","intermediate","advanced","expert"]},"organisationSize":{"type":"array","items":{"type":"string","enum":["micro","small","medium","large"]}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PathwayStage"}},"prerequisites":{"type":"array","items":{"type":"string"}},"outcomes":{"type":"array","items":{"type":"string"}},"estimatedTotalTime":{"type":"string"},"totalRecipes":{"type":"integer"},"dateAdded":{"type":"string","format":"date","description":"YYYY-MM-DD."},"lastUpdated":{"type":"string","format":"date","description":"YYYY-MM-DD."}}}}}}