{"openapi":"3.1.0","info":{"title":"Prospera Havens API","description":"AI-powered Próspera ZEDE property discovery and general market research tools for Roatán, Honduras.\n\nPremium AI endpoints can be accessed through x402 for agents/API clients. Signed-in human users may also receive access through Creem-powered plans or bundles on the website. Free endpoints require no authentication. First-party user-scoped endpoints use a verified Instant session cookie.","version":"1.0.0","contact":{"email":"info@prosperahavens.space"},"x-logo":{"url":"https://prosperahavens.space/icon.png"}},"servers":[{"url":"https://prosperahavens.space","description":"Production"}],"tags":[{"name":"Properties","description":"Browse and search the property catalog"},{"name":"Developments","description":"Real estate developments in Próspera ZEDE"},{"name":"Search","description":"Full-text and AI-powered search"},{"name":"Market","description":"Market statistics and analytics"},{"name":"Events","description":"Community events and webinars"},{"name":"Bookings","description":"Property booking and tour requests"},{"name":"Inquiries","description":"Property inquiries and contact"},{"name":"AI - Free","description":"Free AI-powered features"},{"name":"AI - Paid","description":"Premium AI features (x402 USDC payment required)"},{"name":"User","description":"User-scoped operations for signed-in first-party sessions"}],"components":{"schemas":{"PriceInfo":{"type":"object","properties":{"buyFrom":{"type":"number","nullable":true,"description":"Purchase price in USD"},"rentLongFrom":{"type":"number","nullable":true,"description":"Monthly long-term rent in USD"},"rentShortFrom":{"type":"number","nullable":true,"description":"Nightly short-term rent in USD"},"investFrom":{"type":"number","nullable":true,"description":"Third-party minimum participation amount in USD, if published"},"currency":{"type":"string","enum":["USD","BTC"]}}},"Property":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["studio","1br","2br","penthouse","cabin","villa","condo","coliving","commercial","land"]},"status":{"type":"string","enum":["available","pre_sale","under_construction","sold_out","planned"]},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"areaSqm":{"type":"number"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string","format":"uri"}},"buyFromUsd":{"type":"number","nullable":true},"rentLongFromUsd":{"type":"number","nullable":true},"rentShortFromUsd":{"type":"number","nullable":true},"development":{"$ref":"#/components/schemas/DevelopmentSummary"}}},"DevelopmentSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}},"Development":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"totalUnits":{"type":"integer"},"availableUnits":{"type":"integer"},"location":{"type":"string"},"heroImage":{"type":"string","format":"uri"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"highlights":{"type":"array","items":{"type":"string"}},"priceRange":{"type":"string"},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Property"}}}},"ValuationResult":{"type":"object","properties":{"estimatedValueMin":{"type":"number"},"estimatedValueMax":{"type":"number"},"pricePerSqm":{"type":"number"},"marketAvgPerSqm":{"type":"number"},"premiumDiscount":{"type":"number"},"rentalYieldMin":{"type":"number"},"rentalYieldMax":{"type":"number"},"appreciationOutlook":{"type":"string"},"researchNotes":{"type":"string"},"keyDrivers":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string","enum":["high","medium","low"]}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"x402PaymentRequired":{"type":"object","description":"Returned when x402 payment is required. The response includes payment details in headers.","properties":{"error":{"type":"string","example":"Payment Required"},"accepts":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"price":{"type":"string","example":"$1.00"},"network":{"type":"string","example":"eip155:8453"},"payTo":{"type":"string","example":"0x6Dba39c1122560a81A04054B35591dd618110a33"}}}}}},"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"instant_user_61d46e83-54f1-44de-b1a6-d687e1ac0a43","description":"Verified Instant session cookie used by first-party signed-in flows."},"x402Payment":{"type":"apiKey","in":"header","name":"X-402-Payment","description":"x402 payment proof for premium AI features. See https://x402.org for protocol details. Pay with USDC on Base (eip155:8453)."}}},"paths":{"/api/properties":{"get":{"tags":["Properties"],"summary":"List properties","description":"Browse and filter the property catalog. Supports pagination, filtering by type/status/price/bedrooms, and text search.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["studio","1br","2br","penthouse","cabin","villa","condo","coliving","commercial","land"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["available","pre_sale","under_construction","sold_out"]}},{"name":"minPrice","in":"query","schema":{"type":"number"},"description":"Minimum price in USD"},{"name":"maxPrice","in":"query","schema":{"type":"number"},"description":"Maximum price in USD"},{"name":"bedrooms","in":"query","schema":{"type":"integer"},"description":"Minimum bedrooms"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search"},{"name":"sort","in":"query","schema":{"type":"string","enum":["price_asc","price_desc","newest","area"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Array of properties","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Property"}}}}}}}},"/api/properties/{slug}":{"get":{"tags":["Properties"],"summary":"Get property details","description":"Get full details for a specific property. Supports markdown content negotiation via Accept: text/markdown header for token-efficient agent consumption.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","schema":{"type":"string","enum":["application/json","text/markdown"]},"description":"Set to text/markdown for compact agent-friendly output"}],"responses":{"200":{"description":"Property details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Property"}},"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/developments":{"get":{"tags":["Developments"],"summary":"List developments","description":"Get all real estate developments in Próspera ZEDE with unit counts and price ranges.","responses":{"200":{"description":"Array of developments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Development"}}}}}}}},"/api/developments/{slug}":{"get":{"tags":["Developments"],"summary":"Get development details","description":"Get full details for a development including all its properties. Supports markdown content negotiation.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Development details with properties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Development"}}}},"404":{"description":"Not found"}}}},"/api/search":{"get":{"tags":["Search"],"summary":"Full-text search","description":"Search properties and developments by keyword.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"}],"responses":{"200":{"description":"Search results"}}}},"/api/ai/search":{"post":{"tags":["AI - Free"],"summary":"Natural language search","description":"Parse a natural language query into structured property filters. Free, no payment required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language search, e.g. 'oceanfront villa under $500K'"}},"required":["query"]}}}},"responses":{"200":{"description":"Parsed filters and matching explanation"}}}},"/api/market/stats":{"get":{"tags":["Market"],"summary":"Market statistics","description":"Get market-wide statistics: total properties, average prices, yield ranges, development counts.","responses":{"200":{"description":"Market statistics object"}}}},"/api/events":{"get":{"tags":["Events"],"summary":"List events","description":"Get upcoming community events, webinars, and property tours in Próspera.","responses":{"200":{"description":"Array of events"}}}},"/api/bookings":{"post":{"tags":["Bookings"],"summary":"Book a property","description":"Submit a booking request for a short-term rental property. Works for both anonymous and authenticated users.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"propertyId":{"type":"string"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"totalUsd":{"type":"number"},"guestName":{"type":"string"},"guestEmail":{"type":"string","format":"email"},"guestPhone":{"type":"string"},"notes":{"type":"string"}},"required":["propertyId","checkIn","checkOut","guestName","guestEmail"]}}}},"responses":{"201":{"description":"Booking created"},"400":{"description":"Validation error"}}}},"/api/inquiries":{"post":{"tags":["Inquiries"],"summary":"Submit an inquiry","description":"Submit a property inquiry or tour request. Works for anonymous users.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"propertyId":{"type":"string"},"type":{"type":"string","enum":["inquiry","tour_virtual","tour_in_person"]},"message":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"preferredDate":{"type":"string","format":"date"}},"required":["propertyId","type","message","contactName","contactEmail"]}}}},"responses":{"201":{"description":"Inquiry submitted"},"400":{"description":"Validation error"}}}},"/api/ai/recommendations":{"post":{"tags":["AI - Free"],"summary":"Get property recommendations","description":"ML-powered property recommendations based on preferences. Free, no payment required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"type":"number"},"goal":{"type":"string","enum":["rental_income","capital_appreciation","lifestyle","mixed"]},"propertyType":{"type":"string"},"bedrooms":{"type":"integer"}}}}}},"responses":{"200":{"description":"Recommended properties"}}}},"/api/ai/valuation":{"post":{"tags":["AI - Paid"],"summary":"AI property valuation","description":"Get an AI-powered market value estimate for a Próspera property. Cost: $1.00 USDC via x402 protocol.","x-agent-pricing":{"price":"$1.00","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":["explorer-pack","buyer-pass","investor-pro"]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"development":{"type":"string"},"propertyType":{"type":"string"},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"areaSqm":{"type":"number"},"floor":{"type":"integer"},"oceanView":{"type":"boolean"},"condition":{"type":"string","enum":["new","excellent","good","fair"]}},"required":["development","propertyType","areaSqm"]}}}},"responses":{"200":{"description":"Valuation result","content":{"application/json":{"schema":{"type":"object","properties":{"valuation":{"$ref":"#/components/schemas/ValuationResult"}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/x402PaymentRequired"}}}}}}},"/api/ai/neighborhood":{"post":{"tags":["AI - Paid"],"summary":"AI neighborhood insights","description":"Get AI-powered neighborhood analysis with lifestyle, safety, walkability, and general market context. Cost: $0.50 USDC via x402.","x-agent-pricing":{"price":"$0.50","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":["explorer-pack","buyer-pass"]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"development_slug":{"type":"string"}},"required":["development_slug"]}}}},"responses":{"200":{"description":"Neighborhood insights with scores and nearby places"},"402":{"description":"Payment required"}}}},"/api/ai/listing-generator":{"post":{"tags":["AI - Paid"],"summary":"AI listing generator","description":"Generate professional listing title, description, and pricing insights using AI. Cost: $1.00 USDC via x402.","x-agent-pricing":{"price":"$1.00","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":[]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listing_type":{"type":"string"},"property_type":{"type":"string"},"development":{"type":"string"},"bedrooms":{"type":"integer"},"bathrooms":{"type":"integer"},"area_sqm":{"type":"number"},"price_usd":{"type":"number"},"amenities":{"type":"array","items":{"type":"string"}},"title":{"type":"string"}}}}}},"responses":{"200":{"description":"Generated listing content"},"402":{"description":"Payment required"}}}},"/api/ai/chat":{"post":{"tags":["AI - Paid"],"summary":"AI concierge chat","description":"Stream a conversation with the AI real estate concierge. Supports property search, ROI calculations, tax comparisons, and more. Cost: $0.25 USDC per message via x402. Returns Server-Sent Events (SSE).","x-agent-pricing":{"price":"$0.25","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":["explorer-pack","buyer-pass"]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}}},"required":["messages"]}}}},"responses":{"200":{"description":"SSE stream with text, tool usage, and property results","content":{"text/event-stream":{"schema":{"type":"string"}}}},"402":{"description":"Payment required"}}}},"/api/ai/investment-advisor":{"post":{"tags":["AI - Paid"],"summary":"AI market research brief","description":"Get a general Próspera market research brief using budget, goals, and risk tolerance as educational context. This is not financial, investment, legal, tax, brokerage, escrow, or transaction advice. Cost: $3.00 USDC via x402. Returns SSE stream.","x-agent-pricing":{"price":"$3.00","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":["investor-pro"]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budget_usd":{"type":"number"},"investment_goal":{"type":"string","enum":["rental_income","capital_appreciation","lifestyle","mixed"]},"risk_tolerance":{"type":"string","enum":["conservative","moderate","aggressive"]},"preferred_type":{"type":"string"},"holding_period_years":{"type":"integer"},"payment_method":{"type":"string","enum":["cash","crypto","financing"]}},"required":["budget_usd","investment_goal","risk_tolerance"]}}}},"responses":{"200":{"description":"SSE stream with general market research"},"402":{"description":"Payment required"}}}},"/api/ai/documents":{"post":{"tags":["AI - Paid"],"summary":"AI research worksheet generator","description":"Generate informational worksheets, checklists, and non-legal research templates. This is not legal advice and does not generate transaction-ready legal documents. Cost: $7.00 USDC via x402. Returns SSE stream.","x-agent-pricing":{"price":"$7.00","protocol":"x402","network":"eip155:8453","payTo":"0x6Dba39c1122560a81A04054B35591dd618110a33","facilitator":"https://x402.org/facilitator","currency":"USDC","humanCheckoutAvailable":true,"relatedCreemProducts":["investor-pro"]},"security":[{"x402Payment":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"doc_type":{"type":"string","enum":["purchase_checklist","rental_checklist","residency_notes","nda_review_notes","offer_preparation_notes"]},"buyer_name":{"type":"string"},"seller_name":{"type":"string"},"property_title":{"type":"string"},"purchase_price":{"type":"number"},"special_terms":{"type":"string"}},"required":["doc_type"]}}}},"responses":{"200":{"description":"SSE stream with generated document"},"402":{"description":"Payment required"}}}},"/api/user/profile":{"get":{"tags":["User"],"summary":"Get user profile","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"User profile"},"401":{"description":"Unauthorized"}}},"patch":{"tags":["User"],"summary":"Update user profile","security":[{"sessionCookie":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"walletAddress":{"type":"string"},"preferences":{"type":"object"}}}}}},"responses":{"200":{"description":"Updated profile"}}}},"/api/favorites":{"get":{"tags":["User"],"summary":"List saved properties","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Array of favorited properties"}}},"post":{"tags":["User"],"summary":"Save a property","security":[{"sessionCookie":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"propertyId":{"type":"string"},"priceUsdAtSave":{"type":"number"}},"required":["propertyId"]}}}},"responses":{"201":{"description":"Property saved"}}}},"/api/listings":{"get":{"tags":["User"],"summary":"List my listings","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Array of user's listings"}}},"post":{"tags":["User"],"summary":"Create a listing","security":[{"sessionCookie":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"listingType":{"type":"string","enum":["sell","rent_long","rent_short"]},"askingPrice":{"type":"number"},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Listing created"}}}},"/api/mcp":{"post":{"tags":["AI - Free"],"summary":"MCP Server (Model Context Protocol)","description":"Remote MCP server endpoint using Streamable HTTP transport. Connect any MCP-compatible AI agent (Claude, ChatGPT Workspace Agents, etc.) to interact with Prospera Havens. Supports 16 tools for property search, analysis, bookings, and AI-powered features.","responses":{"200":{"description":"MCP protocol response"}}}}}}