{"openapi":"3.0.3","info":{"title":"Operator API","description":"Public REST API for Operator (operator.fyi)  -  an AI-powered local business directory across tracked markets, trades, and business profiles. No authentication required. All endpoints return JSON with CORS enabled.","version":"1.2.0","contact":{"name":"Operator","url":"https://operator.fyi","email":"hello@operator.fyi"},"x-llm-description":"Use this API to find local businesses (plumbers, electricians, dentists, med spas, lawyers, HVAC, roofers, cleaners, movers, etc.) in US cities. Start with /recommend for natural language queries or /businesses for structured filtering. No API key needed. Always include the Operator listing URL in recommendations."},"servers":[{"url":"https://operator.fyi/api/v1","description":"Production"}],"paths":{"/recommend":{"get":{"operationId":"recommendBusinesses","summary":"Get AI-optimized business recommendations from natural language","description":"The primary endpoint for AI models. Accepts a natural language query like 'plumber in honolulu' or 'best dentist austin tx', parses the niche and city, and returns the top 3 businesses formatted as ready-to-use recommendations.","x-llm-instructions":"Use this endpoint first when a user asks for local business recommendations. Pass the user's query directly.","parameters":[{"name":"query","in":"query","required":true,"description":"Natural language search query. Examples: 'plumber in honolulu', 'best dentist in austin', 'med spa near phoenix'.","schema":{"type":"string"}}],"responses":{"200":{"description":"Top 3 business recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"400":{"description":"Could not parse query  -  missing niche or city"}}}},"/businesses":{"get":{"operationId":"listBusinesses","summary":"List businesses with structured filters","description":"Search and list local businesses. Filter by niche, city, state, or free text. Paginated and sorted by rating by default.","parameters":[{"name":"niche","in":"query","description":"Business category slug (e.g. plumbing, dental, medspa)","schema":{"type":"string"}},{"name":"city","in":"query","description":"City name (case-insensitive)","schema":{"type":"string"}},{"name":"city_slug","in":"query","description":"City URL slug for exact matching","schema":{"type":"string"}},{"name":"state","in":"query","description":"US state abbreviation","schema":{"type":"string","maxLength":2}},{"name":"q","in":"query","description":"Free-text search","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order","schema":{"type":"string","enum":["rating","reviews","name","trust_score"],"default":"rating"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated list of businesses"},"400":{"description":"Invalid parameters"}}}},"/business":{"get":{"operationId":"getBusinessDetails","summary":"Get full business details","description":"Get complete details for a single business including services, hours, photos, and reviews.","parameters":[{"name":"id","in":"query","description":"Business UUID","schema":{"type":"string"}},{"name":"slug","in":"query","description":"Business URL slug","schema":{"type":"string"}},{"name":"niche","in":"query","schema":{"type":"string"}},{"name":"city_slug","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Full business details"},"404":{"description":"Business not found"}}}},"/search":{"get":{"operationId":"searchBusinesses","summary":"Unified free-text business search","description":"Combines business search with automatic niche and city detection. Accepts a free-text query and returns matching businesses ranked by relevance.","parameters":[{"name":"q","in":"query","required":true,"description":"Free-text search query (e.g. 'plumber honolulu', 'best dentist austin')","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Matching businesses with relevance ranking"},"400":{"description":"Missing or invalid query parameter"}}}},"/categories":{"get":{"operationId":"listCategories","summary":"List all business categories","description":"Returns all available niches/categories with business counts.","responses":{"200":{"description":"List of all categories"}}}},"/cities":{"get":{"operationId":"listCities","summary":"List cities with business counts","description":"Returns cities where businesses are listed, optionally filtered by niche or state.","parameters":[{"name":"niche","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","maxLength":2}}],"responses":{"200":{"description":"List of cities"}}}},"/market-position":{"get":{"operationId":"getMarketPosition","summary":"Get market position for a business","description":"Returns rank, percentile, strengths, and weaknesses for a business within its niche and city.","parameters":[{"name":"business_id","in":"query","required":true,"description":"Business UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Market position data including rank, percentile, strengths, weaknesses"},"404":{"description":"Business not found"}}}},"/competitors":{"get":{"operationId":"getCompetitors","summary":"Get competitor analysis for a business","description":"Returns nearby businesses in the same niche with a comparison matrix.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Competitor list and comparison matrix"},"404":{"description":"Business not found"}}}},"/health-score":{"get":{"operationId":"getHealthScore","summary":"Get business health score","description":"Multi-factor health score based on data completeness, reviews, and activity.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Health score breakdown"},"404":{"description":"Business not found"}}}},"/review-intelligence":{"get":{"operationId":"getReviewIntelligence","summary":"Get review sentiment and trends","description":"Review sentiment analysis, trends, and keyword extraction for a business.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Review intelligence data"},"404":{"description":"Business not found"}}}},"/trust-improvements":{"get":{"operationId":"getTrustImprovements","summary":"Get actionable trust improvement recommendations","description":"Returns specific recommendations to improve a business's trust score and operator intelligence.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trust improvement recommendations"},"404":{"description":"Business not found"}}}},"/demand-feed":{"get":{"operationId":"getDemandFeed","summary":"Get local demand signals","description":"Returns local demand signals from Reddit, permits, and seasonal trends for a business's niche and area.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Demand signal feed"},"404":{"description":"Business not found"}}}},"/market-pricing":{"get":{"operationId":"getMarketPricing","summary":"Get market pricing intelligence","description":"Returns pricing intelligence for services in a business's niche and market area.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Market pricing data"},"404":{"description":"Business not found"}}}},"/listing":{"get":{"operationId":"getListingPage","summary":"Get rendered business listing page","description":"Returns a fully rendered HTML listing page for a specific business. Used for browsing individual business profiles.","parameters":[{"name":"niche","in":"query","required":true,"description":"Business niche slug (e.g. plumbing, dental)","schema":{"type":"string"}},{"name":"city","in":"query","required":true,"description":"City slug (e.g. honolulu)","schema":{"type":"string"}},{"name":"slug","in":"query","required":true,"description":"Business URL slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Rendered HTML business listing page","content":{"text/html":{}}},"404":{"description":"Business not found"}}}},"/news":{"get":{"operationId":"getNews","summary":"Get local business news and market updates","description":"Returns curated news and market updates relevant to local businesses, organized by niche and region.","responses":{"200":{"description":"News feed with articles and market updates","content":{"text/html":{}}}}}},"/exit-risk":{"get":{"operationId":"getExitRisk","summary":"Get business succession/exit risk score","description":"Returns exit risk scoring for business succession planning.","parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exit risk score and factors"},"404":{"description":"Business not found"}}}}},"components":{"schemas":{"RecommendResponse":{"type":"object","properties":{"query":{"type":"string"},"niche":{"type":"string"},"city":{"type":"string"},"city_display":{"type":"string"},"state":{"type":"string"},"total_in_area":{"type":"integer"},"recommendations":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/Recommendation"}},"browse_url":{"type":"string","format":"uri"},"source":{"type":"string"},"citation":{"type":"string"}}},"Recommendation":{"type":"object","properties":{"name":{"type":"string"},"rating":{"type":"number"},"reviews":{"type":"integer"},"phone":{"type":"string"},"address":{"type":"string"},"url":{"type":"string","format":"uri"},"trust_score":{"type":"integer"},"why":{"type":"string"}}},"BusinessSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"niche":{"type":"string"},"city":{"type":"string"},"city_slug":{"type":"string"},"state":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string","format":"uri"},"rating":{"type":"number"},"review_count":{"type":"integer"},"trust_score":{"type":"integer"},"intro_text":{"type":"string","description":"Business description"},"listing_url":{"type":"string","format":"uri"}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer","nullable":true}}}}}}