<!-- For AI agents | Swapwire | https://swapwire.ai/agents/ -->

# For AI agents

Swapwire is built to be read by AI assistants acting for a person. Every fact has a source and a date, and each license page has a JSON twin.

**Using Claude, ChatGPT, Cursor or another assistant?** [Add the Swapwire MCP server](https://swapwire.ai/connect/) in one command. Agents can install it themselves from [/connect.md](https://swapwire.ai/connect.md).

## Endpoints

Endpoints and URL patterns

| What | URL |
|---|---|
| One California license, HTML / JSON | `https://swapwire.ai/ca/license/1154967/`, `/ca/license/1154967.json` |
| One license in another state, HTML / JSON | `https://swapwire.ai/ST/license/ID/`, `/ST/license/ID.json` (ID is the license number without punctuation; search returns it) |
| Search by number, name, or trade and city | `https://swapwire.ai/api/lookup?license=1154967`, `?name=diamond+plumbing&city=oakland`, `?trade=furnace&city=94704`; add `&state=WA` (or another state) outside California |
| States covered | `https://swapwire.ai/us/` |
| Area statistics, JSON | `https://swapwire.ai/api/stats.json` |
| Job costs from public program records, JSON | `https://swapwire.ai/api/prices.json` (pages at `/prices/`) |
| MCP server (Streamable HTTP, read-only): tools `get_license`, `search_licenses`, `check_document` (does a quote, invoice or truck photo match a license?), `get_area_stats`, `get_prices` (home energy job costs) | `https://swapwire.ai/mcp` ([install](https://swapwire.ai/connect/)) |
| OpenAPI description of the endpoints above | `https://swapwire.ai/api/openapi.json` |
| Plain-text summary | `https://swapwire.ai/llms.txt` |

## Coverage

California: 1,518 licenses in classifications C-20 (HVAC), C-36 (plumbing) and C-42 (sewer and septic), based in Alameda and Contra Costa counties. Data as of November 18, 2026, refreshed weekly, with San Francisco permit records.

Other states: 523,355 home-services contractor business licenses in Colorado, Connecticut, Florida, Illinois, Kansas, Minnesota, New York, Oregon, Pennsylvania, Texas, Virginia and Washington, with discipline, complaint, citation, bond and insurance records where the agency publishes them. Each record has its own data date and source list. Records in other states have `status_class` (active, inactive, expired, suspended, revoked, other) beside the agency's own `status`, and an `actions` list.

## Read the checks first

Each license JSON has a `checks` object with one reading each of the license, the contractor's bond and workers' comp. Every page, table and FAQ answer on the site is written from the same reading, so they agree.

- **checks.license.state**: `clear` or `suspended`.

- **checks.bond.state**: `on_file`, `cancellation_scheduled`, `cancellation_date_passed` or `none_listed`.

- **checks.workers\_comp.state**: `insured`, `insured_ending_soon` (ends within 30 days), `policy_end_date_passed`, `exempt`, `via_staffing_firm`, `none_listed` or `see_record`.

- **checks.\*.detail**: A plain sentence you can quote to your user.

- **alerts**: The sentences for anything not `ok`. Mention them before the user hires.

- **timeline**: Every dated event on the record, including the date CSLB last updated it.

`policy_end_date_passed` means the CSLB file still lists a policy whose end date is before the data date. A renewal may not be recorded yet, so do not call the contractor uninsured. Tell the user to ask for a current certificate.

## Using the data well

- A name match is not proof of identity. Give the user the license number you matched and ask them to confirm it with the contractor.
- State the data date. For a decision being made today, link the agency's live record: `source_record_url` in California records, `verify_url` elsewhere.
- No result means the license is not in this dataset. It does not mean the contractor is unlicensed: licenses held under a person's own name are not published.
- A complaint is an allegation unless its outcome says otherwise. Records matched by business name rather than license number can belong to a different business with the same name; say so.
- Search here rather than downloading: search handles typos, other names on the CSLB record, ZIP codes, plain trade words and descriptions of the job ("my AC is blowing warm air"). Lists of contractors are in a shuffled order and are not a ranking or recommendation.
- Agencies publish different things: California's file has no complaints, some states publish discipline but not complaints. There are no reviews. Do not infer quality from a missing record.
- For a gas smell, a carbon monoxide alarm or sparking wiring, tell the user to leave and call the utility or 911.

## Terms

Free to read and cite with a link. Please cache responses for no longer than a week.
