{
 "openapi": "3.1.0",
 "info": {
  "title": "Swapwire contractor license API",
  "version": "1.0.0",
  "summary": "Dated facts about California contractor licenses from public CSLB records.",
  "description": "Read-only, no key. Coverage: 1,518 C-20 (HVAC), C-36 (plumbing) and C-42 (sewer and septic) licenses based in Alameda and Contra Costa counties, refreshed weekly; data as of 2026-11-18. A name match is not proof of identity: give the user the license number and ask them to confirm it. No result means not in this dataset, not unlicensed. 60 requests a minute per address. The same data is available as an MCP server at https://swapwire.ai/mcp (https://swapwire.ai/connect/).",
  "contact": {
   "email": "hello@swapwire.ai",
   "url": "https://swapwire.ai/agents/"
  }
 },
 "servers": [
  {
   "url": "https://swapwire.ai"
  }
 ],
 "externalDocs": {
  "description": "Field notes for agents",
  "url": "https://swapwire.ai/agents/"
 },
 "paths": {
  "/api/lookup": {
   "get": {
    "operationId": "searchLicenses",
    "summary": "Search by license number, business name, or trade and city",
    "description": "Give one of: license (a number); name (a business name as written on a quote, with typos and Inc/LLC handled), optionally with city or trade; or, with no name, trade and/or city for a list of licensed contractors. trade can be plain words or a description of the job ('my AC is blowing warm air'); read_as says how it was read. Lists are clear licenses only unless status=all, in a shuffled order fixed until the next refresh, 10 per page, up to 5 pages; they are not rankings.",
    "parameters": [
     {
      "name": "license",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "CSLB license number.",
      "example": "1154967"
     },
     {
      "name": "name",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Business name or part of it.",
      "example": "diamond plumbing"
     },
     {
      "name": "city",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "City name, 'City, CA', or a ZIP code.",
      "example": "Oakland"
     },
     {
      "name": "zip",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ZIP code; same as city=ZIP."
     },
     {
      "name": "trade",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "plumbing, HVAC, sewer, a CSLB code like C-36, or a description of the job.",
      "example": "water heater"
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "clear",
        "all"
       ]
      },
      "description": "Lists only: clear (default) or all."
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 5
      },
      "description": "Lists only."
     }
    ],
    "responses": {
     "200": {
      "description": "Matches (possibly none).",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "mode": {
           "type": "string",
           "enum": [
            "license",
            "name",
            "browse"
           ]
          },
          "data_as_of": {
           "type": "string",
           "format": "date"
          },
          "source": {
           "type": "string"
          },
          "total": {
           "type": "integer"
          },
          "page": {
           "type": "integer"
          },
          "pages": {
           "type": "integer"
          },
          "matches": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "license_number": {
              "type": "string"
             },
             "business_name": {
              "type": "string"
             },
             "other_business_names": {
              "type": "array",
              "items": {
               "type": "string"
              },
              "description": "Other business names on the CSLB record. Names that may be a person's are never included."
             },
             "city": {
              "type": "string"
             },
             "county": {
              "type": "string"
             },
             "status_code": {
              "type": "string",
              "description": "CSLB status code; CLEAR means no suspension."
             },
             "classifications": {
              "type": "array",
              "items": {
               "type": "string"
              },
              "description": "CSLB classes, e.g. C36."
             },
             "years_licensed": {
              "type": [
               "number",
               "null"
              ]
             },
             "summary": {
              "type": "string",
              "description": "One plain sentence: status, trades, years, workers' comp."
             },
             "match_level": {
              "type": "string",
              "enum": [
               "exact",
               "strong",
               "partial",
               "license_number"
              ],
              "description": "Name searches and license lookups only."
             },
             "matched_on": {
              "type": "string",
              "description": "'business name' or 'another name on the CSLB record'."
             },
             "page_url": {
              "type": "string"
             },
             "json_url": {
              "type": "string"
             }
            }
           }
          },
          "read_as": {
           "type": "string",
           "description": "How a plain-language trade was read."
          },
          "did_you_mean": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "note": {
           "type": "string",
           "description": "Say this to the user, or follow it."
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing or unusable parameters; error says what to send."
     },
     "429": {
      "description": "Over 60 requests a minute from one address."
     }
    }
   }
  },
  "/ca/license/{license_number}.json": {
   "get": {
    "operationId": "getLicense",
    "summary": "The full record for one license",
    "description": "Status, classifications, contractor's bond, workers' comp, a checks object with one reading each of the license, bond and workers' comp (each with a plain-sentence detail), alerts, a dated timeline, peer context, data_as_of and source_record_url (the live CSLB record).",
    "parameters": [
     {
      "name": "license_number",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "1154967"
     }
    ],
    "responses": {
     "200": {
      "description": "The record.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not in this dataset. That does not mean the contractor is unlicensed."
     }
    }
   }
  },
  "/api/stats.json": {
   "get": {
    "operationId": "getAreaStats",
    "summary": "Counts by county and trade",
    "description": "Licenses, workers' comp insured and exempt, suspension codes, median years licensed, recent issues.",
    "responses": {
     "200": {
      "description": "Groups by county and trade.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}