{"openapi":"3.0.0","info":{"title":"The Miracle Register API","version":"1.0.0"},"components":{"schemas":{"SaintListItem":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"saint_name":{"type":"string","nullable":true},"canonization_stage":{"type":"string","enum":["saint","blessed","venerable","servant_of_god"]},"feast_day":{"type":"string","nullable":true},"nationality":{"type":"string","nullable":true},"image_url":{"type":"string","nullable":true}},"required":["id","slug","name","saint_name","canonization_stage","feast_day","nationality","image_url"]},"Meta":{"type":"object","nullable":true,"properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true},"total":{"type":"integer","minimum":0},"capped":{"type":"boolean"}},"required":["page","limit","total"]},"SaintDetail":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"saint_name":{"type":"string","nullable":true},"birth_name":{"type":"string","nullable":true},"birth_date":{"type":"string","nullable":true},"death_date":{"type":"string","nullable":true},"feast_day":{"type":"string","nullable":true},"religious_order":{"type":"string","nullable":true},"nationality":{"type":"string","nullable":true},"beatification_date":{"type":"string","nullable":true},"beatified_by":{"type":"string","nullable":true},"canonization_date":{"type":"string","nullable":true},"canonized_by":{"type":"string","nullable":true},"canonization_type":{"type":"string","nullable":true,"enum":["confessor","martyr","virgin","married_couple","other",null]},"canonization_stage":{"type":"string","enum":["saint","blessed","venerable","servant_of_god"]},"patronage":{"type":"array","nullable":true,"items":{"type":"string"}},"themes":{"type":"array","nullable":true,"items":{"type":"string"}},"biography_short":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true,"enum":["male","female","group",null]},"lay_person":{"type":"boolean","nullable":true},"image_url":{"type":"string","nullable":true},"wikipedia_url":{"type":"string","nullable":true},"related_saints":{"type":"array","items":{"$ref":"#/components/schemas/RelatedSaint"}},"miracles":{"type":"array","items":{"$ref":"#/components/schemas/MiracleListItem"}}},"required":["id","slug","name","saint_name","birth_name","birth_date","death_date","feast_day","religious_order","nationality","beatification_date","beatified_by","canonization_date","canonized_by","canonization_type","canonization_stage","patronage","themes","biography_short","gender","lay_person","image_url","wikipedia_url","related_saints","miracles"]},"RelatedSaint":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"relation_type":{"type":"string","enum":["canonized_together","same_order","family"]}},"required":["id","slug","name","relation_type"]},"MiracleListItem":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["healing","nature","eucharistic","stigmata","incorruptibility","apparition","miraculous_image","prophecy","bilocation","other"]},"topics":{"type":"array","nullable":true,"items":{"type":"string"}},"country":{"type":"string","nullable":true},"date_of_event":{"type":"string","nullable":true},"date_precision":{"type":"string","enum":["exact_day","month","year","decade","century","unknown"]},"recipient_name":{"type":"string","nullable":true},"was_medically_verified":{"type":"boolean"},"approval_authority":{"type":"string","enum":["vatican_dicastery","lourdes_bureau","local_bishop","nihil_obstat","none"]},"cure_details":{"type":"string","nullable":true},"used_for_beatification":{"type":"boolean"},"used_for_canonization":{"type":"boolean"},"saints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]}}},"required":["id","slug","title","type","topics","country","date_of_event","date_precision","recipient_name","was_medically_verified","approval_authority","cure_details","used_for_beatification","used_for_canonization","saints"]},"MiracleDetail":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"miracle_category":{"type":"string","enum":["intercessory","associated","apparition"]},"type":{"type":"string","enum":["healing","nature","eucharistic","stigmata","incorruptibility","apparition","miraculous_image","prophecy","bilocation","other"]},"topics":{"type":"array","nullable":true,"items":{"type":"string"}},"date_of_event":{"type":"string","nullable":true},"date_precision":{"type":"string","enum":["exact_day","month","year","decade","century","unknown"]},"timing_relative_to_saint_death":{"type":"string","enum":["during_lifetime","posthumous","not_applicable"]},"location_name":{"type":"string","nullable":true},"location_lat":{"type":"string","nullable":true},"location_lng":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"recipient_name":{"type":"string","nullable":true},"recipient_gender":{"type":"string","nullable":true,"enum":["male","female","not_applicable",null]},"recipient_country":{"type":"string","nullable":true},"recipient_privacy":{"type":"string","enum":["public","first_name_only","confidential","not_applicable"]},"recipient_age_at_event":{"type":"integer","nullable":true},"medical_diagnosis":{"type":"string","nullable":true},"cure_details":{"type":"string","nullable":true},"cure_characteristics":{"type":"string","enum":["instant_complete","gradual_complete","instant_partial","gradual_partial","not_applicable"]},"was_medically_verified":{"type":"boolean"},"medical_verification_date":{"type":"string","nullable":true},"intercessory_medium":{"type":"string","enum":["prayer_only","relic","blessed_oil","medallion","visitation","tomb_prayer","saint_image","not_applicable","other"]},"approval_authority":{"type":"string","enum":["vatican_dicastery","lourdes_bureau","local_bishop","nihil_obstat","none"]},"vatican_decree_date":{"type":"string","nullable":true},"vatican_medical_board_verdict":{"type":"string","nullable":true},"used_for_beatification":{"type":"boolean"},"used_for_canonization":{"type":"boolean"},"witness_count":{"type":"integer","nullable":true},"synopsis":{"type":"string","nullable":true},"has_primary_sources":{"type":"boolean"},"saints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"}},"required":["id","slug","name"]}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/MiracleImage"}}},"required":["id","slug","title","miracle_category","type","topics","date_of_event","date_precision","timing_relative_to_saint_death","location_name","location_lat","location_lng","country","region","recipient_name","recipient_gender","recipient_country","recipient_privacy","recipient_age_at_event","medical_diagnosis","cure_details","cure_characteristics","was_medically_verified","medical_verification_date","intercessory_medium","approval_authority","vatican_decree_date","vatican_medical_board_verdict","used_for_beatification","used_for_canonization","witness_count","synopsis","has_primary_sources","saints","sources","images"]},"Source":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"title":{"type":"string","nullable":true},"source_type":{"type":"string","enum":["vatican_decree","news_article","book","academic","other"]},"accessed_date":{"type":"string","nullable":true}},"required":["id","url","title","source_type","accessed_date"]},"MiracleImage":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"caption":{"type":"string","nullable":true},"display_order":{"type":"integer"},"source_attribution":{"type":"string","nullable":true}},"required":["id","url","caption","display_order","source_attribution"]},"MiracleTypeItem":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"}},"required":["type","label"]},"Metadata":{"type":"object","properties":{"miracle_types":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}},"miracle_categories":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}},"approval_authorities":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}},"miracle_topics":{"type":"array","items":{"type":"string"}},"saint_themes":{"type":"array","items":{"type":"string"}}},"required":["miracle_types","miracle_categories","approval_authorities","miracle_topics","saint_themes"]},"SearchResult":{"type":"object","properties":{"type":{"type":"string","enum":["saint","miracle"]},"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":"string","nullable":true}},"required":["type","slug","title","excerpt"]}},"parameters":{}},"paths":{"/api/v1/saints":{"get":{"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["saint","blessed","venerable","servant_of_god"]},"required":false,"name":"canonization_stage","in":"query"},{"schema":{"type":"string","enum":["hope","perseverance","conversion","eucharistic","marian","martyrs","missionaries","saints-of-everyday-life","spiritual-direction","technology"]},"required":false,"name":"theme","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"religious_order","in":"query"},{"schema":{"type":"string","maxLength":100},"required":false,"name":"nationality","in":"query"}],"responses":{"200":{"description":"List of saints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaintListItem"}},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/saints/{slug}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Saint detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SaintDetail"},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/miracles":{"get":{"parameters":[{"schema":{"type":"integer","nullable":true},"required":false,"name":"saint_id","in":"query"},{"schema":{"type":"string","enum":["healing","nature","eucharistic","stigmata","incorruptibility","apparition","miraculous_image","prophecy","bilocation","other"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["children","mothers","pregnancy-and-childbirth","marriage","youth","elderly","addiction","prisoners","loss-grief","native-and-indigenous","veterans","religious-life","conversion"]},"required":false,"name":"topic","in":"query"},{"schema":{"type":"string","enum":["intercessory","associated","apparition"]},"required":false,"name":"category","in":"query"},{"schema":{"type":"string"},"required":false,"name":"country","in":"query"},{"schema":{"type":"integer","nullable":true},"required":false,"name":"year_from","in":"query"},{"schema":{"type":"integer","nullable":true},"required":false,"name":"year_to","in":"query"},{"schema":{"type":"string"},"required":false,"name":"used_for_beatification","in":"query"},{"schema":{"type":"string"},"required":false,"name":"used_for_canonization","in":"query"},{"schema":{"type":"string","enum":["vatican_dicastery","lourdes_bureau","local_bishop","nihil_obstat"]},"required":false,"name":"approval_authority","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of miracles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MiracleListItem"}},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/miracles/{slug}":{"get":{"parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Miracle detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MiracleDetail"},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/types":{"get":{"responses":{"200":{"description":"List of miracle types","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MiracleTypeItem"}},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/metadata":{"get":{"responses":{"200":{"description":"Canonical filter options for the API","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Metadata"},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}},"/api/v1/search":{"get":{"parameters":[{"schema":{"type":"string","minLength":2},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["children","mothers","pregnancy-and-childbirth","marriage","youth","elderly","addiction","prisoners","loss-grief","native-and-indigenous","veterans","religious-life","conversion","hope","perseverance","eucharistic","marian","martyrs","missionaries","saints-of-everyday-life","spiritual-direction","technology"]},"required":false,"name":"topic","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"meta":{"$ref":"#/components/schemas/Meta"},"error":{"type":"string","nullable":true}},"required":["data","meta","error"]}}}}}}}}}