{"openapi":"3.1.0","info":{"title":"Satsang open directory API","version":"0.2.0","description":"Read-only, no-auth API over Satsang (tantrafiles.xyz): wisdom traditions and schools, teachers and lineages, places to practise with contacts as published, free texts, practices and talks. Every record has url (canonical page to cite), source_url, verified_on and confidence. Licence: CC BY 4.0 for Satsang curation; third-party data is metadata under its own terms. Same data as the MCP server at /mcp.","contact":{"url":"https://tantrafiles.xyz/agents"},"license":{"name":"CC BY 4.0 (data), MIT (code)","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://mcp.tantrafiles.xyz"}],"paths":{"/api/search":{"get":{"operationId":"search","summary":"Search everything","description":"Search teachers, traditions, topics, practices, texts, collections, places and talks. Returns {results:[{id,title,url}]}; pass id to /api/fetch.","parameters":[{"name":"q","in":"query","required":true,"description":"Search words, e.g. \"Ajahn Chah\" or \"Zen monastery Japan\".","schema":{"type":"string"}},{"name":"kinds","in":"query","required":false,"description":"Comma list: person,tradition,topic,practice,resource,collection,place,clip","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 10).","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/fetch":{"get":{"operationId":"fetchRecord","summary":"Fetch one record","description":"Full record by id from search (e.g. person/ajahn-chah, place/amaravati): {id,title,text,url,metadata} with source_url, verified_on, confidence.","parameters":[{"name":"id","in":"query","required":true,"description":"Record id such as person/ajahn-chah or a tantrafiles.xyz URL.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/places":{"get":{"operationId":"findPlaces","summary":"Find places to practise","description":"Monasteries, retreat centres, ashrams, temples, sacred sites. Filters: tradition (incl. schools), school, country, region, type, status, living_teacher, offers.","parameters":[{"name":"tradition","in":"query","required":false,"description":"e.g. theravada, Tibetan Buddhism, sufism","schema":{"type":"string"}},{"name":"school","in":"query","required":false,"description":"Exact school, e.g. thai-forest","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO code(s) or names, comma-separated","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"europe, north-america, south-asia, southeast-asia, east-asia, oceania, south-america, middle-east, africa, asia, americas","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"monastery, retreat, centre, ashram, temple, pilgrimage, retreat-centre, study-centre, sacred-site","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"active, heritage or any","schema":{"type":"string","enum":["active","heritage","any"]}},{"name":"living_teacher","in":"query","required":false,"description":"Only places tied to a living teacher","schema":{"type":"boolean"}},{"name":"offers","in":"query","required":false,"description":"Comma list that must all match, e.g. residential,10-day or sanskrit","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free words","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/places/search":{"get":{"operationId":"searchPlaces","summary":"Search places (all filters)","description":"Free text plus tradition, school, country, near (lat, lng, km; nearest first with distance_km), residential, online, language, has_upcoming_events, has_email.","parameters":[{"name":"q","in":"query","required":false,"description":"Free words, e.g. silent retreat","schema":{"type":"string"}},{"name":"tradition","in":"query","required":false,"description":"Tradition (incl. schools)","schema":{"type":"string"}},{"name":"school","in":"query","required":false,"description":"Exact school","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO code(s) or names","schema":{"type":"string"}},{"name":"lat","in":"query","required":false,"description":"Latitude for near","schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"description":"Longitude for near","schema":{"type":"number"}},{"name":"km","in":"query","required":false,"description":"Radius in km (default 100)","schema":{"type":"number"}},{"name":"residential","in":"query","required":false,"description":"true = can stay","schema":{"type":"boolean"}},{"name":"online","in":"query","required":false,"description":"true = online or hybrid","schema":{"type":"boolean"}},{"name":"language","in":"query","required":false,"description":"e.g. en, de, Thai","schema":{"type":"string"}},{"name":"has_upcoming_events","in":"query","required":false,"description":"Dated events in the next 90 days","schema":{"type":"boolean"}},{"name":"has_email","in":"query","required":false,"description":"Publishes an email","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/events":{"get":{"operationId":"listEvents","summary":"Upcoming events","description":"Dated events (next 90 days) read weekly from each place’s own iCal feed or schema.org Event data, with source and fetched_at.","parameters":[{"name":"place","in":"query","required":false,"description":"Place id","schema":{"type":"string"}},{"name":"tradition","in":"query","required":false,"description":"Tradition (incl. schools)","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO code(s) or names","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"YYYY-MM-DD","schema":{"type":"string"}},{"name":"online","in":"query","required":false,"description":"Online only","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"Words in the event name","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/places/{id}":{"get":{"operationId":"getPlace","summary":"Place details","description":"One place: contacts exactly as published with source and check date, programmes with as-of date, teachers, sister places, events, resources.","parameters":[{"name":"id","in":"path","required":true,"description":"Place id, e.g. amaravati","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/teachers":{"get":{"operationId":"findTeachers","summary":"Find teachers","description":"Teachers, scholars and figures by tradition, school, living status, country/region (via their places), role and on_video.","parameters":[{"name":"tradition","in":"query","required":false,"description":"Tradition (incl. schools)","schema":{"type":"string"}},{"name":"school","in":"query","required":false,"description":"Exact school","schema":{"type":"string"}},{"name":"living","in":"query","required":false,"description":"true = living or likely living","schema":{"type":"boolean"}},{"name":"country","in":"query","required":false,"description":"ISO code(s)","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Region","schema":{"type":"string"}},{"name":"role","in":"query","required":false,"description":"teacher, scholar, figure","schema":{"type":"string","enum":["teacher","scholar","figure","translator","founder","author"]}},{"name":"on_video","in":"query","required":false,"description":"Has talks on Satsang","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"Free words","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/teachers/{id}":{"get":{"operationId":"getTeacher","summary":"Teacher profile","description":"Bio, years, works, best talks, lineage relations and places for one person.","parameters":[{"name":"id","in":"path","required":true,"description":"Person id, e.g. thanissaro-bhikkhu","schema":{"type":"string"}},{"name":"talks","in":"query","required":false,"description":"Number of talks","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/resources":{"get":{"operationId":"getResources","summary":"Texts and books","description":"Texts, books and libraries per tradition, person or topic, free (publisher’s own free edition) vs paid-or-unknown.","parameters":[{"name":"tradition","in":"query","required":false,"description":"Tradition","schema":{"type":"string"}},{"name":"person","in":"query","required":false,"description":"Person id or name","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"Topic id","schema":{"type":"string"}},{"name":"free","in":"query","required":false,"description":"Only free","schema":{"type":"boolean"}},{"name":"kind","in":"query","required":false,"description":"book, text, scripture, essay, library","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free words","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 25).","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/lineage/path":{"get":{"operationId":"getLineagePath","summary":"Lineage path","description":"Shortest documented chain between two people (teacher-student, ordination, academic supervision, influence) with confidence and sources.","parameters":[{"name":"from","in":"query","required":true,"description":"Person id or name","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"Person id or name","schema":{"type":"string"}},{"name":"lineage","in":"query","required":false,"description":"all, dharma, academic, influence, institutional","schema":{"type":"string"}},{"name":"max_hops","in":"query","required":false,"description":"Default 8","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/lineage/{id}":{"get":{"operationId":"getLineage","summary":"Lineage around a person","description":"Teacher-student / academic edges up and down from a person or tradition.","parameters":[{"name":"id","in":"path","required":true,"description":"Person or tradition id","schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"description":"up, down or both","schema":{"type":"string"}},{"name":"lineage","in":"query","required":false,"description":"dharma, academic, influence, all","schema":{"type":"string"}},{"name":"hops","in":"query","required":false,"description":"Default 3","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/study/{tradition}":{"get":{"operationId":"whatToStudy","summary":"Study path for a tradition","description":"Orientation, then free online resources, practices and talks, then teachers (living first), then places to go.","parameters":[{"name":"tradition","in":"path","required":true,"description":"e.g. thai-forest, zen, kashmir-shaivism","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per step (default 6)","schema":{"type":"integer","default":6}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/topics/{id}":{"get":{"operationId":"getTopic","summary":"Topic across traditions","description":"A topic (rebirth, death, self, karma...) with intro, questions, one-line takes per tradition, diverse talks, practices, texts.","parameters":[{"name":"id","in":"path","required":true,"description":"Topic id, e.g. rebirth","schema":{"type":"string"}},{"name":"talks","in":"query","required":false,"description":"Number of talks","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/practices":{"get":{"operationId":"listPractices","summary":"Practices","description":"Practices with plain steps, sources and cautions; filter by tradition, kind, topic.","parameters":[{"name":"tradition","in":"query","required":false,"description":"Tradition","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"description":"meditation, visualisation, enquiry, chant, ritual, movement","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"Topic id","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/collections":{"get":{"operationId":"listCollections","summary":"Collections","description":"Curated sets, journeys and syllabi.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/collections/{id}":{"get":{"operationId":"getCollection","summary":"One collection","description":"A journey, syllabus or set with its ordered units and resolved items.","parameters":[{"name":"id","in":"path","required":true,"description":"Collection id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/retreats":{"get":{"operationId":"findRetreats","summary":"Find retreats","description":"Recurring programmes places publish (typical length, format, cost model, recurrence) with the official schedule link and last-confirmed date. No dated instances: dates come from the schedule page.","parameters":[{"name":"country","in":"query","required":false,"description":"ISO code(s) or names","schema":{"type":"string"}},{"name":"tradition","in":"query","required":false,"description":"Tradition or school","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"residential, non-residential, online, mixed","schema":{"type":"string"}},{"name":"length","in":"query","required":false,"description":"e.g. 10-day, weekend, long, ongoing","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free words","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 20).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/schedule/{id}":{"get":{"operationId":"getSchedule","summary":"Place schedule","description":"One place: programmes, yearly events (usual month), official schedule page (canonical for dates), last-checked dates.","parameters":[{"name":"id","in":"path","required":true,"description":"Place id, e.g. wat-ram-poeng","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/retreat-plan":{"get":{"operationId":"planRetreat","summary":"Plan a home retreat","description":"One whole talk per day (never cut), a timetable scaled by strictness, rules overlay, warnings when it is a study week rather than a retreat, and places that run real retreats. Nothing is booked.","parameters":[{"name":"topic","in":"query","required":true,"description":"e.g. death, metta, awakening","schema":{"type":"string"}},{"name":"days","in":"query","required":true,"description":"1-365","schema":{"type":"integer","minimum":1,"maximum":365}},{"name":"strictness","in":"query","required":false,"description":"gentle, standard or strict","schema":{"type":"string"}},{"name":"tradition","in":"query","required":false,"description":"Tradition, optional","schema":{"type":"string"}},{"name":"teacher","in":"query","required":false,"description":"Person id or name, optional","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/booking-draft":{"get":{"operationId":"composeBooking","summary":"Draft a booking enquiry","description":"Email text for the user to send themselves, from the contacts the place publishes. Never sends, books or takes payment; without a published email it returns the official page instead.","parameters":[{"name":"place","in":"query","required":true,"description":"Place id","schema":{"type":"string"}},{"name":"dates","in":"query","required":true,"description":"e.g. 2027-01-04 to 2027-01-30","schema":{"type":"string"}},{"name":"programme","in":"query","required":false,"description":"Programme id or name, optional","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}},"/api/recommend":{"get":{"operationId":"recommend","summary":"Recommend talks","description":"Diverse talks from liked ids (clip ids, person/<id>, topic/<id>, tradition/<id>) plus next topics.","parameters":[{"name":"liked","in":"query","required":false,"description":"Comma list of liked ids","schema":{"type":"string"}},{"name":"disliked","in":"query","required":false,"description":"Comma list","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"Restrict to a topic","schema":{"type":"string"}},{"name":"k","in":"query","required":false,"description":"How many (default 8)","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"404":{"description":"Unknown id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (Retry-After header)"}}}}},"components":{"schemas":{"Result":{"type":"object","additionalProperties":true,"description":"Tool result. Records carry url (canonical tantrafiles.xyz page), source_url, verified_on (YYYY-MM-DD) and confidence (high|medium|low)."},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}