{
  "openapi": "3.1.0",
  "info": {
    "title": "AssistAnt pro directory",
    "version": "1.0.0",
    "description": "Free, read-only API over a nationwide U.S. directory of appliance repair, dryer vent cleaning and used-appliance businesses. Verified businesses (registration and insurance checked by AssistAnt, with the date) come first, then distance. Placement cannot be bought and AssistAnt never sells a person's information. Rules: https://assistant247.net/how-we-verify. Also available as an MCP server at https://assistant247.net/mcp.",
    "contact": {
      "url": "https://assistant247.net/pros"
    },
    "license": {
      "name": "Listings include Overture Maps Foundation data (CDLA-Permissive-2.0)",
      "url": "https://cdla.dev/permissive-2-0/"
    }
  },
  "servers": [
    {
      "url": "https://assistant247.net"
    }
  ],
  "paths": {
    "/api/pros": {
      "get": {
        "operationId": "findPros",
        "summary": "Find appliance pros near a U.S. ZIP code or coordinates",
        "description": "Returns businesses ordered verified-first, then by match and distance. If a problem is given, free repair guides that match come back first (help before a sales call). Never a dead end: when nothing is within 40 miles, a nationwide video-diagnosis option is returned.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            },
            "description": "5-digit U.S. ZIP code (or give lat and lon)"
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "appliance_repair",
                "dryer_vent_cleaning",
                "used_appliances",
                "appliance_store",
                "duct_cleaning"
              ],
              "default": "appliance_repair"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. samsung, lg, whirlpool, ge, sub-zero, viking, speed-queen"
          },
          {
            "name": "appliance",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "refrigerator",
                "freezer",
                "ice_maker",
                "washer",
                "dryer",
                "dishwasher",
                "oven_range",
                "microwave",
                "wine_cooler",
                "disposal"
              ]
            }
          },
          {
            "name": "problem",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "What is wrong, in plain words, including any error code"
          },
          {
            "name": "segment",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "residential",
                "commercial"
              ],
              "default": "residential"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown location"
          }
        }
      }
    },
    "/pros/{slug}": {
      "get": {
        "operationId": "getProProfile",
        "summary": "One business's full listing",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Last part of the profile URL"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such listing"
          },
          "410": {
            "description": "Removed at the business's request"
          }
        }
      }
    },
    "/{service}/{state}/{town}": {
      "get": {
        "operationId": "getTownSummary",
        "summary": "Counts and the listed-first businesses within 25 miles of a town",
        "parameters": [
          {
            "name": "service",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "appliance-repair",
                "dryer-vent-cleaning",
                "used-appliances"
              ]
            }
          },
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter state, lowercase (la)"
          },
          {
            "name": "town",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Town slug (covington, new-orleans, saint-louis)"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Town summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No page for that town yet"
          }
        }
      }
    },
    "/appliances/{brand}/{appliance}": {
      "get": {
        "operationId": "getApplianceKnowledge",
        "summary": "What technicians actually found on a brand + appliance (from real repair records)",
        "description": "Counts from TN Appliance Exchange repair records (what the technician found on diagnosed jobs). Not a reliability ranking. Also /appliances/{appliance}?format=json and /appliances?format=json.",
        "parameters": [
          {
            "name": "brand",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "samsung, lg, whirlpool, ge, frigidaire, maytag, kenmore, hisense"
          },
          {
            "name": "appliance",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "refrigerator",
                "washer",
                "dryer",
                "dishwasher",
                "oven-range"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Findings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Not enough records for that brand and appliance"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "free_help_first": {
            "type": "object",
            "description": "Matching free repair guides, shown before any business"
          },
          "no_pro_nearby": {
            "type": "object"
          },
          "privacy": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pro"
            }
          },
          "ranking": {
            "type": "string"
          },
          "how_we_verify": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Pro": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "brands_named": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "appliances_named": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "trust": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string",
                "enum": [
                  "listed",
                  "verified_public",
                  "verified_data"
                ]
              },
              "label": {
                "type": "string"
              },
              "claimed_by_business": {
                "type": "boolean"
              },
              "verified_on": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "bookable_online": {
            "type": "boolean"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "distance_miles": {
            "type": "number"
          },
          "profile": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}