{"openapi":"3.1.0","info":{"title":"ServiceForge Directory API","version":"2026-10-09","description":"Find local home-service pros (plumbing, HVAC, roofing, electrical and 30+ trades) in the ServiceForge Directory. Public listing data: name, trade, phone, hours, Google rating, service area, listing and booking links. Claimed and Human Verified pros come first. With the homeowner's OK, request a callback from a pro (their phone is verified by a text code). No key needed. MCP server: https://pro.serviceforge.com/mcp (streamable HTTP).","contact":{"email":"directory@serviceforge.com","url":"https://pro.serviceforge.com/developers"}},"servers":[{"url":"https://pro.serviceforge.com"}],"paths":{"/v1/pros":{"get":{"operationId":"searchPros","summary":"Search local home-service pros by trade and place","parameters":[{"name":"trade","in":"query","schema":{"type":"string"},"description":"e.g. plumbing, hvac, roofing, electrician"},{"name":"city","in":"query","schema":{"type":"string"},"description":"City name, e.g. Dallas"},{"name":"state","in":"query","schema":{"type":"string","minLength":2,"maxLength":2},"description":"Two-letter US state code"},{"name":"zip","in":"query","schema":{"type":"string","pattern":"^\\d{5}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}}],"responses":{"200":{"description":"Matching pros, claimed and Human Verified first.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"query":{"type":"object"},"total":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Pro"}}}}}}},"404":{"description":"Not found, or not an active listing."},"429":{"description":"Rate limited (60 requests a minute per IP)."}}}},"/api/search":{"get":{"operationId":"siteSearch","summary":"Search listings by any words: business name, trade, city or phone digits","description":"Active listings only, best first, up to 60. The same results as a page: https://pro.serviceforge.com/?q=","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":80},"description":"e.g. roof repair dallas"}],"responses":{"200":{"description":"Matching listings (card fields: id, name, slug, address, phone, rating, claim state, city, category).","content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string"},"total":{"type":"integer"},"limit":{"type":"integer"},"businesses":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"q missing, shorter than 2 or longer than 80 characters."}}}},"/v1/pros/{id}":{"get":{"operationId":"getPro","summary":"Get one pro's public listing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pro"}}}},"404":{"description":"Not found, or not an active listing."},"429":{"description":"Rate limited (60 requests a minute per IP)."}}}},"/v1/profile/{slug}":{"get":{"operationId":"getProfile","summary":"Structured profile (JSON-LD fields) for a claimed or Human Verified listing","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile JSON."},"404":{"description":"Not found, or not an active listing."},"429":{"description":"Rate limited (60 requests a minute per IP)."}}}}},"components":{"schemas":{"Pro":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"trade":{"type":"object","properties":{"name":{"type":["string","null"]},"slug":{"type":["string","null"]}}},"claimStatus":{"type":"string","enum":["verified","claimed","unclaimed"]},"phone":{"type":["string","null"]},"hours":{"description":"Weekly opening hours, or null when unknown."},"rating":{"type":["object","null"],"properties":{"value":{"type":"number"},"count":{"type":"integer"},"source":{"type":"string","enum":["google"]}}},"serviceArea":{"type":"object","properties":{"areas":{"type":"array","items":{"type":"string"}},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}}},"emergencyService":{"type":["boolean","null"]},"temporarilyClosed":{"type":"boolean"},"listingUrl":{"type":["string","null"],"format":"uri"},"bookingUrl":{"type":["string","null"],"format":"uri"},"websiteUrl":{"type":["string","null"],"format":"uri"}},"required":["id","name","trade","claimStatus"]}}}}