{
  "product": "Contractor License Verification API",
  "version": "v1",
  "description": "A clean, normalized REST API that verifies US contractor licenses across states — status, expiry, classification, bond/insurance — aggregated from official public-records sources.",
  "integrity": "Every record is reported verbatim from an official public-records source with a source_url and as_of date. Status and dates are never invented, altered, reordered for pay, or editorialized. Partial state coverage is flagged, never hidden.",
  "states_covered": [
    "WA",
    "OR",
    "CA"
  ],
  "total_records": 299112,
  "pricing": "Pre-launch (Stage 0). Free during the probe; pay-per-use planned. No key required yet.",
  "endpoints": [
    {
      "path": "/v1/lookup",
      "method": "GET",
      "purpose": "Verify a single license by number (the core call).",
      "params": {
        "state": "WA|OR|CA (required)",
        "license": "license number (required)"
      },
      "example": "https://license-verify.pages.dev/v1/lookup?state=CA&license=1000002"
    },
    {
      "path": "/v1/search",
      "method": "GET",
      "purpose": "Search by business / principal name.",
      "params": {
        "q": "name query, >=2 chars, matched from the first character (required)",
        "state": "WA|OR|CA (optional; defaults to all)",
        "status": "active|suspended|expired (optional)",
        "limit": "1-100 (default 25)",
        "offset": "default 0"
      },
      "example": "https://license-verify.pages.dev/v1/search?q=construction&state=OR&status=active"
    },
    {
      "path": "/v1/licenses",
      "method": "GET",
      "purpose": "Paged by-state list (license#-sorted compact records).",
      "params": {
        "state": "WA|OR|CA (required)",
        "page": "0-based page index (default 0)",
        "status": "filter within page (optional)",
        "city": "filter within page (optional)"
      },
      "example": "https://license-verify.pages.dev/v1/licenses?state=WA&page=0"
    },
    {
      "path": "/v1/states",
      "method": "GET",
      "purpose": "Coverage & freshness table (counts, as_of, sources, partial flags).",
      "example": "https://license-verify.pages.dev/v1/states"
    },
    {
      "path": "/v1/mcp",
      "method": "POST",
      "purpose": "MCP server (JSON-RPC 2.0 over Streamable HTTP) for AI agents. Same data, four tools: lookup_license, search_licenses, list_licenses, get_coverage. GET this URL for a capability summary.",
      "example": "https://license-verify.pages.dev/v1/mcp"
    }
  ],
  "mcp": {
    "endpoint": "https://license-verify.pages.dev/v1/mcp",
    "protocol": "Model Context Protocol over Streamable HTTP (JSON-RPC 2.0). POST initialize / tools/list / tools/call.",
    "tools": [
      "lookup_license",
      "search_licenses",
      "list_licenses",
      "get_coverage"
    ]
  },
  "notes": [
    "Every record carries source_url + as_of. Status/dates are reported verbatim, never invented.",
    "Some states are bootstrap slices flagged partial:true in /v1/states — coverage is disclosed, never hidden.",
    "AI agents can call the same data over MCP at /v1/mcp (no key required during the Stage-0 probe)."
  ]
}