{"openapi":"3.1.0","info":{"title":"MylesShephard.com AI Property Search API","version":"2026.05.27","summary":"Authenticated property-search and buyer-action tools for AI assistants.","description":"Use this API to let a verified user search active Tri-Cities area property listings, retrieve listing detail with default photos and indexed page links, save searches, watch properties, and request buyer follow-up from Myles Shephard."},"servers":[{"url":"https://mylesshephard.com"}],"tags":[{"name":"Authentication","description":"Email confirmation flow for AI assistants."},{"name":"Listings","description":"Search and retrieve locally indexed active property listings."},{"name":"Buyer actions","description":"Create buyer requests, saved searches, and watched-property alerts."}],"paths":{"/api/ai-agent/auth/request":{"post":{"tags":["Authentication"],"operationId":"requestEmailAuthenticationCode","summary":"Start email authentication","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"clientName":{"type":"string","description":"Name of the AI assistant or client requesting access."}}}}}},"responses":{"201":{"description":"Confirmation email sent."},"400":{"description":"Invalid email or request."}}}},"/api/ai-agent/auth/verify":{"post":{"tags":["Authentication"],"operationId":"verifyEmailAuthenticationCode","summary":"Verify email code and receive bearer token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","minLength":6,"maxLength":6},"clientName":{"type":"string"}}}}}},"responses":{"200":{"description":"Bearer token issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTokenResponse"}}}}}}},"/api/ai-agent/me":{"get":{"tags":["Authentication"],"operationId":"getAuthenticatedPropertySearchUser","security":[{"bearerAuth":[]}],"summary":"Get the authenticated public user profile","responses":{"200":{"description":"Public user profile."},"401":{"description":"Authentication required."}}}},"/api/ai-agent/listings":{"get":{"tags":["Listings"],"operationId":"searchPropertyListings","security":[{"bearerAuth":[]}],"summary":"Search active property listings","description":"Returns concise active listing summaries with SEO indexed page URLs and the default locally cached photo. Homes are searched by default; include land or commercial property types explicitly when needed.","parameters":[{"name":"city","in":"query","schema":{"type":"array","items":{"type":"string"}},"explode":true,"description":"One or more Michigan cities or local areas to search, such as Saginaw Township."},{"name":"county","in":"query","schema":{"type":"array","items":{"type":"string"}},"explode":true,"description":"One or more counties to include, such as Saginaw, Bay, or Midland. Omit to search every county in the local feed."},{"name":"minPrice","in":"query","schema":{"type":"integer","minimum":0}},{"name":"maxPrice","in":"query","schema":{"type":"integer","minimum":0}},{"name":"minBeds","in":"query","schema":{"type":"number","minimum":0}},{"name":"minBaths","in":"query","schema":{"type":"number","minimum":0}},{"name":"minSqft","in":"query","schema":{"type":"integer","minimum":0}},{"name":"minAcres","in":"query","schema":{"type":"number","minimum":0}},{"name":"schoolDistrict","in":"query","schema":{"type":"array","items":{"type":"string"}},"explode":true},{"name":"bodyOfWater","in":"query","schema":{"type":"array","items":{"type":"string","enum":["saginaw_river","lake_huron","inland_lake","river","canal","pond","other"]}},"explode":true,"description":"Optional waterfront subtype filter, such as saginaw_river, lake_huron, or inland_lake."},{"name":"waterBodyName","in":"query","schema":{"type":"array","items":{"type":"string"}},"explode":true,"description":"Optional named water body, such as Saginaw River."},{"name":"propertyType","in":"query","schema":{"type":"array","items":{"type":"string","enum":["residential","condo","multi_family","manufactured","rental","land","commercial"]}},"explode":true},{"name":"features","in":"query","schema":{"type":"array","items":{"type":"string"}},"explode":true,"description":"Optional preference terms such as garage, basement, pole barn, fenced yard, waterfront."},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","updated","price_desc","price_asc"],"default":"newest"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":12}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pass the nextCursor from a previous response to continue the same search."},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0},"description":"Numeric offset. Prefer cursor when continuing a previous result set."},{"name":"includeThumbs","in":"query","schema":{"type":"boolean","default":true},"description":"Includes a small base64 WebP thumbnail in photoThumbBase64 for agent card rendering inside restrictive iframes. Pass false for text-only responses."}],"responses":{"200":{"description":"Matching property listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearchResponse"}}}}}}},"/api/ai-agent/listings/{listingId}":{"get":{"tags":["Listings"],"operationId":"getPropertyListing","security":[{"bearerAuth":[]}],"summary":"Get listing detail","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string"}},{"name":"includeThumbs","in":"query","schema":{"type":"boolean","default":true},"description":"When true, include a small base64 WebP thumbnail in photoThumbBase64 for inline agent rendering."}],"responses":{"200":{"description":"Listing detail with photos and required listing-office attribution.","content":{"application/json":{"schema":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/ListingDetail"}}}}}},"404":{"description":"Listing not found."}}}},"/api/ai-agent/listings/{listingId}/request":{"post":{"tags":["Buyer actions"],"operationId":"requestPropertyInformationOrShowing","security":[{"bearerAuth":[]}],"summary":"Log a buyer request for one property","description":"Use when a verified user asks for information, buyer representation, or a showing. This creates a buyer lead for Myles to follow up.","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyRequestInput"}}}},"responses":{"201":{"description":"Request logged."},"400":{"description":"Missing contact information."}}}},"/api/ai-agent/listings/{listingId}/watch":{"post":{"tags":["Buyer actions"],"operationId":"watchProperty","security":[{"bearerAuth":[]}],"summary":"Watch one property for status and price updates","parameters":[{"name":"listingId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"alertEmailEnabled":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Property watch saved."}}}},"/api/ai-agent/saved-searches":{"post":{"tags":["Buyer actions"],"operationId":"savePropertySearch","security":[{"bearerAuth":[]}],"summary":"Save the current search and email alerts","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedSearchInput"}}}},"responses":{"201":{"description":"Saved search created or updated."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"myles_agent_token"}},"schemas":{"AuthTokenResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"tokenType":{"type":"string","enum":["Bearer"]},"accessToken":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"openapiUrl":{"type":"string","format":"uri"},"user":{"$ref":"#/components/schemas/PublicUser"}}},"PublicUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"verifiedAt":{"type":["string","null"],"format":"date-time"}}},"ListingSearchResponse":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/ListingSummary"}},"totalCount":{"type":"integer"},"returned":{"type":"integer"},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]},"searchPath":{"type":"string","format":"uri"},"filters":{"type":"object"},"thumbsIncluded":{"type":"boolean"}}},"ListingSummary":{"type":"object","properties":{"listingId":{"type":"string"},"url":{"type":"string","format":"uri"},"address":{"type":"string"},"fullAddress":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"price":{"type":["number","null"]},"propertyType":{"type":"string"},"status":{"type":"string"},"image":{"type":"string","format":"uri"},"defaultPhoto":{"type":"string","format":"uri"},"photoUrlFull":{"type":"string","format":"uri"},"photoThumbBase64":{"type":"string","description":"Base64-encoded inline WebP thumbnail when includeThumbs/include_thumbs is requested. Render with data:image/webp;base64, plus this value."},"photoThumbMimeType":{"type":"string","enum":["image/webp",""]},"relatedListingIds":{"type":"array","items":{"type":"string"}},"priceConfidence":{"type":"string","enum":["high","low","unknown"]},"priceOutlier":{"type":"boolean"},"dataQualityFlags":{"type":"array","items":{"type":"string"}},"facts":{"type":"array","items":{"type":"object"}},"listingOffice":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"waterfront":{"type":"boolean"},"waterBodyName":{"type":["string","null"]},"waterBodyType":{"type":["string","null"],"enum":["saginaw_river","lake_huron","inland_lake","river","canal","pond","other",null]}}},"ListingDetail":{"allOf":[{"$ref":"#/components/schemas/ListingSummary"},{"type":"object","properties":{"remarks":{"type":"string"},"bedrooms":{"type":["number","null"]},"bathrooms":{"type":["number","null"]},"livingArea":{"type":["integer","null"]},"lotSizeAcres":{"type":["number","null"]},"lotSqft":{"type":["integer","null"]},"yearBuilt":{"type":["integer","null"]},"garageSpaces":{"type":["number","null"]},"taxAnnual":{"type":["number","null"]},"taxYear":{"type":["integer","null"]},"schools":{"type":"object"},"hoa":{"type":["object","null"]},"listingAgent":{"type":"object"},"statusHistory":{"type":"array","items":{"type":"object"}},"similarListings":{"type":"array","items":{"$ref":"#/components/schemas/ListingSummary"}},"schoolDistricts":{"type":"array","items":{"type":"string"}},"photos":{"type":"array","items":{"type":"object"}},"listingCourtesy":{"type":"object"}}}]},"PropertyRequestInput":{"type":"object","required":["name","phone"],"additionalProperties":false,"properties":{"action":{"type":"string","enum":["information","showing","representation","offer"],"default":"information"},"name":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"requestText":{"type":"string"},"financingStatus":{"type":"string"}}},"SavedSearchInput":{"type":"object","required":["filters"],"additionalProperties":true,"properties":{"name":{"type":"string"},"filters":{"type":"object"},"alertEmailEnabled":{"type":"boolean","default":true}}}}}}