API & AI Search
You can query retreatsfyi using AI tools like Claude Code, allowing you to search for retreats using natural language instead of manually setting filters.
How it works
Our API exposes retreat data in a format that AI assistants can understand and query. Simply ask your AI tool to find retreats matching your criteria, and it will construct the appropriate API calls for you.
Using Claude Code
Claude Code is a command-line AI assistant that can browse the web and make API requests. Here's how to use it with retreatsfyi:
# First, ask Claude to check what filters are available:
"Fetch the schema from retreatsfyi.com/api/v1/retreats/schema and tell me what filters I can use"
# Then, ask for retreats in natural language:
"Find me week-long vipassana retreats in the UK this summer for beginners"
Claude will translate your request into API parameters and return matching retreats.
API Endpoints
GET /api/v1/retreats/schema
Returns available filters, valid values for each filter, and lists of retreat centers and teachers. AI tools should fetch this first to understand what queries are possible.
GET /api/v1/retreats
Returns all upcoming retreats. Supports filtering via query parameters.
GET /api/v1/retreats/:id
Returns detailed information about a specific retreat, including pricing tiers.
Available Filters
| Parameter | Description |
|---|---|
| q | Full-text search on title and description |
| start_date, end_date | Date range (YYYY-MM-DD). Finds retreats overlapping these dates. |
| min_duration, max_duration | Duration in days |
| latitude, longitude, radius_km | Location-based search (radius defaults to 100km) |
| retreat_format[] | residential, day, online, hybrid |
| style[] | vipassana, zen, tibetan, secular, mixed, theravada, insight |
| experience_level[] | all_levels, beginner, intermediate, advanced |
| available_only | Set to 1 to exclude full retreats |
| sort | date_asc, date_desc, duration_asc, duration_desc, price_asc, price_desc, distance |
Example Queries
Here are some natural language queries you might try:
- "Find weekend Zen retreats near San Francisco"
- "Show me 10-day vipassana courses in Europe for beginners"
- "What insight meditation retreats are available at Gaia House this spring?"
- "Find residential retreats under 500km from London in March, at least 5 days long"
Rate Limits
The API is rate-limited to 60 requests per minute per IP address. Please be mindful of this when building integrations.
Other AI Tools
Any AI assistant that can make HTTP requests can use this API. This includes:
- Claude Code (Anthropic)
- ChatGPT with browsing or Code Interpreter
- Custom agents built with LangChain, AutoGPT, etc.
- Any MCP-compatible tool