{"openapi":"3.1.0","info":{"title":"Own Your Listing API","version":"0.1.0","description":"Merchant-owned, machine-readable directory of local businesses. Also available over MCP; see /.well-known/mcp/server-card.json."},"servers":[{"url":"https://api.ownyourlisting.com"}],"components":{"schemas":{"SearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ListingSummary"}},"has_more":{"type":"boolean"},"query_interpretation":{"type":"string"}},"required":["results","has_more","query_interpretation"]},"ListingSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"schema_org_type":{"type":"string"},"address":{"type":"object","properties":{"street_address":{"type":"string"},"locality":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"}},"required":["street_address","locality","region","postal_code","country_code"]},"geo":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]},"distance_m":{"type":["number","null"]},"verification_state":{"type":"string"},"tier":{"type":"string"},"price_range":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"canonical_url":{"type":["string","null"]},"score":{"type":"number"}},"required":["id","slug","name","category","schema_org_type","address","geo","distance_m","verification_state","tier","price_range","phone","website","canonical_url","score"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]},"Listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","minLength":3,"maxLength":96,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"name":{"type":"string","minLength":2,"maxLength":200},"category":{"type":"string","enum":["dentist","med-spa","dermatologist","hair-salon","nail-salon","barbershop","day-spa","general-contractor"]},"address":{"type":"object","properties":{"street_address":{"type":"string","minLength":3,"maxLength":200},"locality":{"type":"string","minLength":2,"maxLength":120},"region":{"type":"string","minLength":2,"maxLength":2},"postal_code":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"country_code":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$","default":"US"}},"required":["street_address","locality","region","postal_code"]},"geo":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180}},"required":["lat","lng"]},"verification_state":{"type":"string","enum":["unverified","self_asserted","license_verified","domain_verified","fully_verified","expired","revoked"]},"tier":{"type":"string","enum":["free","verified","featured"]},"price_range":{"type":["string","null"],"maxLength":12,"default":null},"phone":{"type":["string","null"],"pattern":"^\\+[1-9]\\d{7,14}$","default":null},"website":{"type":["string","null"],"format":"uri","default":null},"canonical_url":{"type":["string","null"],"format":"uri"},"description":{"type":["string","null"],"maxLength":4000,"default":null},"timezone":{"type":"string","minLength":3,"maxLength":64,"default":"America/New_York"},"status":{"type":"string","enum":["draft","published","suppressed"]},"verification":{"type":"object","properties":{"state":{"type":"string","enum":["unverified","self_asserted","license_verified","domain_verified","fully_verified","expired","revoked"]},"scope":{"type":"string","minLength":10,"maxLength":400},"evidence":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["email_domain","phone_otp","dns_txt","well_known_file","license_match","gbp_oauth","manual_review"]},"authority":{"type":["string","null"],"maxLength":160,"default":null},"reference":{"type":["string","null"],"maxLength":160,"default":null},"checked_at":{"type":"string","format":"date-time"}},"required":["method","checked_at"]},"default":[]},"verified_at":{"type":["string","null"],"format":"date-time","default":null},"expires_at":{"type":["string","null"],"format":"date-time","default":null},"last_checked_at":{"type":["string","null"],"format":"date-time","default":null}},"required":["state","scope"]},"hours":{"type":"array","items":{"type":"object","properties":{"day_of_week":{"type":"integer","minimum":0,"maximum":6},"opens":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$"},"closes":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$"},"closed":{"type":"boolean","default":false}},"required":["day_of_week","opens","closes"]},"default":[]},"hours_exceptions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"opens":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$"},"closes":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d(:[0-5]\\d)?$"},"closed":{"type":"boolean","default":true},"label":{"type":["string","null"],"maxLength":120,"default":null}},"required":["date","opens","closes"]},"default":[]},"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":160},"description":{"type":["string","null"],"maxLength":600,"default":null},"price_min_minor":{"type":["integer","null"],"minimum":0,"default":null},"price_max_minor":{"type":["integer","null"],"minimum":0,"default":null},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"duration_minutes":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":1440,"default":null}},"required":["name"]},"default":[]},"endpoints":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["booking","mcp","a2a","api","webmcp","payments","x402"]},"url":{"type":"string","format":"uri"},"auth_type":{"type":"string","enum":["none","api_key","oauth2","bearer"],"default":"none"},"spec_url":{"type":["string","null"],"format":"uri","default":null},"verified":{"type":"boolean","default":false}},"required":["kind","url"]},"default":[]},"updated_at":{"type":"string","format":"date-time"},"schema_org_type":{"type":"string"},"credentials":{"type":"array","items":{"type":"object","properties":{"authority":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":["string","null"]},"status":{"type":"string"},"issued_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"last_checked_at":{"type":["string","null"]}},"required":["authority","license_number","license_type","status","issued_at","expires_at","last_checked_at"]}}},"required":["id","slug","name","category","address","geo","verification_state","tier","canonical_url","status","verification","updated_at","schema_org_type","credentials"]}},"parameters":{}},"paths":{"/v1/listings":{"get":{"summary":"Search listings","description":"Ranked local-business search by location, category and free text. Coordinates are rounded to 3 decimal places and the radius snapped to a bucket so that nearby queries share a cache entry.","parameters":[{"schema":{"type":"string","maxLength":200},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"category","in":"query"},{"schema":{"type":["number","null"],"minimum":-90,"maximum":90},"required":false,"name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180},"required":false,"name":"lng","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":200},"required":false,"name":"radius_km","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"verified_only","in":"query"},{"schema":{"type":"string"},"required":false,"name":"open_at","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":1000},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Ranked results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/{slug}":{"get":{"summary":"Get a listing","description":"Full public profile including hours, services, endpoints and verification detail.","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"The listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/{slug}/verification":{"get":{"summary":"Verification report for a listing","description":"What has actually been verified about this business and how stale the check is. Returns the licence records behind the claim, never a bare boolean: in some verticals no single licence exists, so 'verified: true' would be misleading.","parameters":[{"schema":{"type":"string"},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Verification report","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/categories":{"get":{"summary":"List categories","description":"The category vocabulary, with the schema.org type each maps to.","responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{}}}}}}}},"webhooks":{}}