{"openapi":"3.0.3","info":{"title":"MiddleVerse AI Discovery API","description":"AI-native business directory API for discovering local businesses, sending inquiries to claimed listings, and making bookings only where paid booking capability is enabled.","version":"1.0.0","contact":{"name":"MiddleVerse Support","email":"Melinda@middleverse.ai","url":"https://middleverse.ai"},"license":{"name":"Proprietary","url":"https://middleverse.ai/terms"}},"servers":[{"url":"https://middleverse.ai","description":"Production server"}],"tags":[{"name":"Discovery","description":"AI discovery feeds for browsing available businesses by category"},{"name":"Businesses","description":"Business listing and search operations"},{"name":"Booking","description":"Paid, entitlement-gated booking operations"},{"name":"Inquiries","description":"Contact-only email inquiries for claimed listings; these never create bookings or commerce transactions"},{"name":"Directory","description":"Directory pages and search"}],"paths":{"/api/ai-discovery":{"get":{"tags":["Discovery"],"operationId":"getAIDiscoveryFeed","summary":"Get AI discovery feed","description":"Main feed for AI platforms - returns categories with sample businesses. AI assistants use this to understand what's available without fetching everything.","responses":{"200":{"description":"Schema.org ItemList of business categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}}}}},"/api/ai-discovery/categories":{"get":{"tags":["Discovery"],"operationId":"getCategories","summary":"Get all business categories","description":"Full category list with business counts and cities served","responses":{"200":{"description":"List of all categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}}}}},"/api/ai-discovery/category/{category}":{"get":{"tags":["Discovery"],"operationId":"getBusinessesByCategory","summary":"Get businesses in a category","description":"Returns all businesses in a specific category with full Schema.org structured data","parameters":[{"name":"category","in":"path","required":true,"description":"Category name (e.g., 'restaurant', 'auto_detailing', 'coffee_shop')","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"Filter by city name","schema":{"type":"string"}}],"responses":{"200":{"description":"List of businesses in the category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessList"}}}}}}},"/api/public/businesses":{"get":{"tags":["Businesses"],"operationId":"listBusinesses","summary":"List all businesses","description":"Returns a list of active businesses with optional filtering. Response includes Schema.org ItemList format for AI consumption.","parameters":[{"name":"category","in":"query","required":false,"description":"Filter by business category","schema":{"type":"string"}},{"name":"location","in":"query","required":false,"description":"Filter by city or state","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results (default: 50, max: 100)","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Schema.org ItemList of businesses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessList"}}}}}}},"/api/public/businesses/{slug}":{"get":{"tags":["Businesses"],"operationId":"getBusinessBySlug","summary":"Get business details","description":"Returns full business details with Schema.org LocalBusiness structured data","parameters":[{"name":"slug","in":"path","required":true,"description":"Business URL slug (e.g., 'people-wizards')","schema":{"type":"string"}}],"responses":{"200":{"description":"Business details with Schema.org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"}}}},"404":{"description":"Business not found"}}}},"/api/directory/search":{"get":{"tags":["Directory"],"operationId":"searchDirectory","summary":"Search businesses","description":"Full-text search across business names, descriptions, and categories","parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"Filter by city","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter by category","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessList"}}}}}}},"/api/public/ai-booking/inquiry":{"post":{"tags":["Inquiries"],"operationId":"sendClaimedListingInquiry","summary":"Email a question or reservation inquiry to a claimed business","description":"Free contact-only relay for claimed, publicly visible listings. A successful response means the inquiry was emailed to the business owner; it does not create or confirm a booking, check a calendar, reserve inventory, or collect payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryRequest"}}}},"responses":{"200":{"description":"Inquiry accepted for email delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryResponse"}}}},"400":{"description":"Invalid inquiry"},"404":{"description":"No claimed, publicly visible listing found"}}}},"/api/public/ai-booking/book":{"post":{"tags":["Booking"],"operationId":"createBooking","summary":"Create a booking","description":"Paid, entitlement-gated endpoint for actual appointments or reservations. Do not use this merely to contact a business; use /api/public/ai-booking/inquiry instead. For restaurant reservations, include partySize and dietaryRestrictions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"200":{"description":"Booking created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingResponse"}}}},"400":{"description":"Invalid booking request"},"404":{"description":"Business not found"}}}},"/api/public/ai-booking/availability/{businessSlug}":{"get":{"tags":["Booking"],"operationId":"getAvailability","summary":"Get business availability","description":"Check available booking slots for a business","parameters":[{"name":"businessSlug","in":"path","required":true,"description":"Business URL slug","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Date to check (ISO 8601 format)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Available time slots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}}}}},"/b/{slug}":{"get":{"tags":["Directory"],"operationId":"getBusinessPage","summary":"Get business HTML page","description":"Server-rendered HTML page with Schema.org JSON-LD for AI crawlers and human visitors","parameters":[{"name":"slug","in":"path","required":true,"description":"Business URL slug","schema":{"type":"string"}}],"responses":{"200":{"description":"HTML page with embedded Schema.org JSON-LD","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Business not found"}}}},"/b/{slug}.jsonld":{"get":{"tags":["Directory"],"operationId":"getBusinessJsonLd","summary":"Get the canonical business JSON-LD entity","description":"Machine-readable Schema.org representation of the same public business entity rendered at /b/{slug}.","parameters":[{"name":"slug","in":"path","required":true,"description":"Business URL slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Business, WebPage, and BreadcrumbList JSON-LD graph","content":{"application/ld+json":{"schema":{"$ref":"#/components/schemas/Business"}}}},"404":{"description":"Business not found"}}}},"/c/{city}/{category}":{"get":{"tags":["Directory"],"operationId":"getDirectoryPage","summary":"Get directory listing page","description":"Server-rendered HTML directory page listing businesses by city and category","parameters":[{"name":"city","in":"path","required":true,"description":"City slug (e.g., 'seattle', 'new-york')","schema":{"type":"string"}},{"name":"category","in":"path","required":true,"description":"Category slug (e.g., 'pizza', 'auto-detailing')","schema":{"type":"string"}}],"responses":{"200":{"description":"HTML directory page with Schema.org ItemList","content":{"text/html":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"Business":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"LocalBusiness"},"@id":{"type":"string","description":"Canonical URL for the business"},"name":{"type":"string","description":"Business name"},"description":{"type":"string","description":"Business description"},"url":{"type":"string","format":"uri","description":"Business page URL"},"telephone":{"type":"string","description":"Phone number"},"email":{"type":"string","format":"email","description":"Email address"},"address":{"$ref":"#/components/schemas/PostalAddress"},"geo":{"$ref":"#/components/schemas/GeoCoordinates"},"category":{"type":"string","description":"Business category (Yelp/Google style)"},"priceRange":{"type":"string","enum":["$","$$","$$$","$$$$"],"description":"Price range indicator"},"aggregateRating":{"$ref":"#/components/schemas/AggregateRating"},"potentialAction":{"$ref":"#/components/schemas/ReserveAction"}}},"BusinessList":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"ItemList"},"name":{"type":"string"},"numberOfItems":{"type":"integer"},"itemListElement":{"type":"array","items":{"type":"object","properties":{"@type":{"type":"string","example":"ListItem"},"position":{"type":"integer"},"item":{"$ref":"#/components/schemas/Business"}}}}}},"CategoryList":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"ItemList"},"name":{"type":"string"},"itemListElement":{"type":"array","items":{"type":"object","properties":{"@type":{"type":"string","example":"ListItem"},"position":{"type":"integer"},"item":{"type":"object","properties":{"name":{"type":"string","description":"Category name"},"numberOfItems":{"type":"integer","description":"Number of businesses in category"}}}}}}}},"PostalAddress":{"type":"object","properties":{"@type":{"type":"string","example":"PostalAddress"},"streetAddress":{"type":"string"},"addressLocality":{"type":"string","description":"City"},"addressRegion":{"type":"string","description":"State/Province"},"postalCode":{"type":"string"},"addressCountry":{"type":"string","default":"US"}}},"GeoCoordinates":{"type":"object","properties":{"@type":{"type":"string","example":"GeoCoordinates"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"AggregateRating":{"type":"object","properties":{"@type":{"type":"string","example":"AggregateRating"},"ratingValue":{"type":"number","minimum":0,"maximum":5},"reviewCount":{"type":"integer"},"bestRating":{"type":"string","example":"5"},"worstRating":{"type":"string","example":"1"}}},"ReserveAction":{"type":"object","properties":{"@type":{"type":"string","example":"ReserveAction"},"target":{"type":"object","properties":{"@type":{"type":"string","example":"EntryPoint"},"urlTemplate":{"type":"string","format":"uri"},"httpMethod":{"type":"string","example":"POST"},"contentType":{"type":"string","example":"application/json"}}}}},"InquiryRequest":{"type":"object","required":["businessSlug","customerName","customerEmail","message"],"properties":{"businessSlug":{"type":"string","description":"Business URL slug"},"customerName":{"type":"string","maxLength":160},"customerEmail":{"type":"string","format":"email","maxLength":320},"customerPhone":{"type":"string","maxLength":80},"message":{"type":"string","maxLength":4000},"inquiryType":{"type":"string","enum":["question","reservation"],"default":"question"},"aiPlatform":{"type":"string","maxLength":100}}},"InquiryResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"status":{"type":"string","example":"received"}}},"BookingRequest":{"type":"object","required":["businessSlug","customerName","customerEmail","dateTime"],"properties":{"businessSlug":{"type":"string","description":"Business URL slug"},"customerName":{"type":"string","description":"Customer full name"},"customerEmail":{"type":"string","format":"email","description":"Customer email"},"customerPhone":{"type":"string","description":"Customer phone number"},"dateTime":{"type":"string","format":"date-time","description":"Requested booking date/time (ISO 8601)"},"serviceType":{"type":"string","description":"Type of service requested"},"notes":{"type":"string","description":"Additional notes for the booking"},"partySize":{"type":"integer","minimum":1,"maximum":500,"description":"Number of people (for restaurants, events, etc.). Stored on the reservation and shown in the restaurant's kitchen view."},"dietaryRestrictions":{"type":"array","items":{"type":"string"},"description":"Dietary restrictions or allergies for the party, e.g. [\"gluten-free\", \"nut allergy\"]. Also accepts a single comma-separated string. Stored on the reservation and surfaced to the restaurant's kitchen staff."}}},"BookingResponse":{"type":"object","properties":{"success":{"type":"boolean"},"bookingId":{"type":"string","description":"Unique booking reference"},"status":{"type":"string","enum":["confirmed","pending","waitlist"],"description":"Booking status"},"businessName":{"type":"string"},"dateTime":{"type":"string","format":"date-time"},"confirmationUrl":{"type":"string","format":"uri","description":"URL to view/manage the booking"}}},"AvailabilityResponse":{"type":"object","properties":{"businessSlug":{"type":"string"},"date":{"type":"string","format":"date"},"slots":{"type":"array","items":{"type":"object","properties":{"startTime":{"type":"string","format":"time"},"endTime":{"type":"string","format":"time"},"available":{"type":"boolean"}}}}}}}}}