{
  "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",
    "FL"
  ],
  "total_records": 441247,
  "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|FL (required)",
        "license": "license number (required)"
      },
      "example": "https://license-verify.pages.dev/v1/lookup?state=CA&license=1000002"
    },
    {
      "path": "/v1/batch",
      "method": "POST",
      "purpose": "Verify many licenses in one request (the bulk-verification call).",
      "body": {
        "licenses": "array of {state, license} objects (max 25)"
      },
      "example": "POST https://license-verify.pages.dev/v1/batch  {\"licenses\":[{\"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|FL (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|FL (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/changes",
      "method": "GET",
      "purpose": "Dated license status-change ledger (the monitoring call: re-check a portfolio for newly suspended/expired licenses).",
      "params": {
        "since": "YYYY-MM-DD (optional)",
        "state": "WA|OR|CA|FL (optional)",
        "type": "status_changed|added|removed (optional)",
        "limit": "1-500 (default 50)"
      },
      "example": "https://license-verify.pages.dev/v1/changes?since=2026-06-01&state=CA&type=status_changed"
    },
    {
      "path": "/v1/mcp",
      "method": "POST",
      "purpose": "MCP server (JSON-RPC 2.0 over Streamable HTTP) for AI agents. Same data, six tools: lookup_license, verify_licenses (batch), search_licenses, list_licenses, get_coverage, get_recent_changes. 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",
      "verify_licenses",
      "search_licenses",
      "list_licenses",
      "get_coverage",
      "get_recent_changes"
    ]
  },
  "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)."
  ]
}