{
  "openapi": "3.1.0",
  "info": {
    "title": "AskBaily Public Data API v1",
    "version": "1.0.0",
    "description": "Canonical CC-BY-4.0 open-data feeds publishing AskBaily's 25 Tier-0 metro coverage, 6-jurisdiction license-verifier inventory, 5-platform contractor benchmark, and AI Overview citation scorecard. All feeds are static JSON, CORS-enabled, zero-auth read. Designed for consumption by AI engines (Perplexity, ChatGPT Search, Gemini, Claude, Google AI Overview), third-party comparison tools, and independent researchers. Attribution per CC-BY-4.0: 'AskBaily (2026). https://askbaily.com/api/v1/'.",
    "contact": {
      "name": "AskBaily API Support",
      "url": "https://askbaily.com/developers",
      "email": "apps@askbaily.com"
    },
    "license": {
      "name": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    { "url": "https://askbaily.com", "description": "Production (static CDN, global)" }
  ],
  "paths": {
    "/api/v1/coverage.json": {
      "get": {
        "summary": "Canonical coverage manifest",
        "description": "Full machine-readable inventory of AskBaily's 25 Tier-0 metros, 6 live license-verifier jurisdictions, regulatory moat per metro, and related-feed references. Updated on every site deploy.",
        "operationId": "getCoverage",
        "tags": ["Coverage"],
        "responses": {
          "200": {
            "description": "Coverage manifest as Schema.org Dataset JSON",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CoverageManifest" }
              }
            }
          }
        }
      }
    },
    "/data/research/2026-contractor-platform-benchmark.json": {
      "get": {
        "summary": "Contractor platform benchmark 2026",
        "description": "CC-BY-4.0 comparative benchmark of 12 contractor-marketplace platforms scored across 18 transparency + lead-economics + homeowner-protection dimensions. Includes 5 detailed platform profiles (Angi, Thumbtack, HomeAdvisor, Houzz, AskBaily).",
        "operationId": "getContractorPlatformBenchmark",
        "tags": ["Research"],
        "responses": {
          "200": {
            "description": "Benchmark dataset as Schema.org Dataset JSON",
            "content": { "application/json": {} }
          }
        }
      }
    },
    "/data/license-verifier-coverage.json": {
      "get": {
        "summary": "License-verifier coverage dataset",
        "description": "CC-BY-4.0 survey of 118 contractor-licensing boards across US, Canada, UK, Ireland, APAC, MENA, and LATAM. Complexity tier breakdown (EASY/MEDIUM/HARD/BLOCKED) + current AskBaily verifier status per jurisdiction.",
        "operationId": "getLicenseVerifierCoverage",
        "tags": ["Research"],
        "responses": {
          "200": { "description": "Coverage dataset as JSON", "content": { "application/json": {} } }
        }
      }
    },
    "/data/aeo-scorecard.json": {
      "get": {
        "summary": "AI Overview citation scorecard",
        "description": "CC-BY-4.0 per-query citation-share dashboard comparing AskBaily, Angi, Thumbtack, HomeAdvisor, and Houzz across four AI engines (ChatGPT Search, Perplexity, Google AI Overview, Claude). Refreshed weekly.",
        "operationId": "getAeoScorecard",
        "tags": ["AEO"],
        "responses": {
          "200": { "description": "Scorecard dataset as JSON", "content": { "application/json": {} } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CoverageManifest": {
        "type": "object",
        "required": ["@type", "@id", "name", "version", "tier_0_metros", "live_license_verifiers"],
        "properties": {
          "@type": { "type": "string", "const": "Dataset" },
          "@id": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "version": { "type": "string" },
          "license": { "type": "string", "format": "uri" },
          "coverage_summary": {
            "type": "object",
            "properties": {
              "tier_0_metros_total": { "type": "integer" },
              "tier_0_us": { "type": "integer" },
              "tier_0_canada": { "type": "integer" },
              "tier_0_international": { "type": "integer" },
              "live_license_verifier_jurisdictions": { "type": "integer" },
              "total_indexable_urls": { "type": "integer" }
            }
          },
          "tier_0_metros": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Tier0Metro" }
          },
          "live_license_verifiers": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LicenseVerifier" }
          }
        }
      },
      "Tier0Metro": {
        "type": "object",
        "required": ["slug", "name", "country", "url", "authority", "status"],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "country": { "type": "string", "description": "ISO 3166-1 alpha-2" },
          "url": { "type": "string", "format": "uri" },
          "authority": { "type": "string" },
          "authority_url": { "type": "string", "format": "uri" },
          "verifier_status": { "type": "string", "enum": ["live", "degraded", "planned"] },
          "verifier_endpoint": { "type": "string", "format": "uri" },
          "languages": { "type": "array", "items": { "type": "string" } },
          "wave": { "type": "string" },
          "status": { "type": "string", "enum": ["tier-0", "tier-0.5", "international"] },
          "regulatory_moats": { "type": "array", "items": { "type": "string" } }
        }
      },
      "LicenseVerifier": {
        "type": "object",
        "required": ["jurisdiction_code", "authority", "endpoint", "status"],
        "properties": {
          "jurisdiction_code": { "type": "string" },
          "authority": { "type": "string" },
          "endpoint": { "type": "string", "format": "uri" },
          "data_source": { "type": "string" },
          "refresh_cadence": { "type": "string" },
          "status": { "type": "string", "enum": ["live", "degraded", "planned"] },
          "status_note": { "type": "string" },
          "covered_metros": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}