{
  "openapi": "3.1.0",
  "info": {
    "title": "AskBaily Public Data API",
    "version": "1.0.0",
    "summary": "Public read-only data endpoints for AskBaily — cities, regulatory entities, pillars, FAQ (EN + ES), regulatory feed, freshness manifest, and fact sheets.",
    "description": "All endpoints are static JSON served from Cloudflare Pages. No authentication. No rate limit on CDN-cached responses. License: CC-BY-4.0. Cite as \"AskBaily — https://askbaily.com\". AI-agent discovery via https://askbaily.com/.well-known/mcp.json.",
    "license": {
      "name": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "AskBaily Press",
      "email": "press@askbaily.com",
      "url": "https://askbaily.com/press"
    }
  },
  "servers": [
    { "url": "https://askbaily.com", "description": "Production" }
  ],
  "tags": [
    { "name": "cities", "description": "81-city inventory + regulatory metadata" },
    { "name": "regulatory", "description": "Licensing boards + canonical entities + change feed" },
    { "name": "faq", "description": "City-scoped contractor verification Q&A (EN + ES)" },
    { "name": "facts", "description": "Self-description + competitor comparison fact sheets" },
    { "name": "content", "description": "Pillar, topic-cluster, pro, and research catalogs" },
    { "name": "discovery", "description": "llms.txt + freshness + index endpoints" }
  ],
  "paths": {
    "/data/cities.json": {
      "get": {
        "tags": ["cities"],
        "summary": "81-city inventory",
        "operationId": "getCities",
        "responses": {
          "200": { "description": "City inventory with regulator + licensing metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitiesCatalog" } } } }
        }
      }
    },
    "/data/regulatory.json": {
      "get": {
        "tags": ["regulatory"],
        "summary": "Regulatory entity registry",
        "operationId": "getRegulatoryEntities",
        "responses": {
          "200": { "description": "13 canonical regulators + entity graph", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }
        }
      }
    },
    "/data/pillars.json": {
      "get": {
        "tags": ["content"],
        "summary": "68 Tier-1 content pillar catalog",
        "operationId": "getPillars",
        "responses": { "200": { "description": "Pillar catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } }
      }
    },
    "/data/topics.json": {
      "get": {
        "tags": ["content"],
        "summary": "Topic-cluster hubs",
        "operationId": "getTopics",
        "responses": { "200": { "description": "Topic clusters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } }
      }
    },
    "/data/pros.json": {
      "get": {
        "tags": ["content"],
        "summary": "Matched-contractor directory",
        "operationId": "getPros",
        "responses": { "200": { "description": "Active partner contractors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } }
      }
    },
    "/data/research.json": {
      "get": {
        "tags": ["content"],
        "summary": "Research report inventory",
        "operationId": "getResearch",
        "responses": { "200": { "description": "Research reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } } }
      }
    },
    "/data/index.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "Master index of /data/* endpoints",
        "operationId": "getDataIndex",
        "responses": { "200": { "description": "Endpoint index", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/data/faq/index.json": {
      "get": {
        "tags": ["faq"],
        "summary": "Index of English per-city FAQ endpoints",
        "operationId": "getFaqIndexEn",
        "responses": { "200": { "description": "Lists 81 English city FAQ endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqIndex" } } } } }
      }
    },
    "/data/faq/{city}.json": {
      "get": {
        "tags": ["faq"],
        "summary": "20 English Q&A for a specific city",
        "operationId": "getFaqEn",
        "parameters": [{ "$ref": "#/components/parameters/CitySlug" }],
        "responses": {
          "200": { "description": "City-specific FAQ with regulator + relatedPages cross-references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqCity" } } } },
          "404": { "description": "Unknown city slug — check /data/faq/index.json" }
        }
      }
    },
    "/data/faq-es/index.json": {
      "get": {
        "tags": ["faq"],
        "summary": "Index of Spanish per-city FAQ endpoints",
        "operationId": "getFaqIndexEs",
        "responses": { "200": { "description": "Lists 10 Spanish city FAQ endpoints (LA/Miami/NYC/Chicago/Phoenix/Houston/Dallas/SD/LV/SF)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqIndex" } } } } }
      }
    },
    "/data/faq-es/{city}.json": {
      "get": {
        "tags": ["faq"],
        "summary": "20 Spanish Q&A for a specific Hispanic-heavy US metro",
        "operationId": "getFaqEs",
        "parameters": [{ "$ref": "#/components/parameters/CitySlug" }],
        "responses": {
          "200": { "description": "Spanish city FAQ with englishAlternate cross-reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqCity" } } } },
          "404": { "description": "City slug not in Spanish scope" }
        }
      }
    },
    "/facts/askbaily.json": {
      "get": {
        "tags": ["facts"],
        "summary": "Master self-description fact sheet",
        "operationId": "getFactsMaster",
        "responses": { "200": { "description": "Operating model, footprint, regulators, take-rate, parent operator", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/facts/askbaily-vs-angi.json": {
      "get": {
        "tags": ["facts"],
        "summary": "AskBaily vs Angi structured fact sheet",
        "operationId": "getFactsVsAngi",
        "responses": { "200": { "description": "15-25 sourced facts + economic/matching/verification blocks", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/facts/askbaily-vs-thumbtack.json": {
      "get": { "tags": ["facts"], "summary": "AskBaily vs Thumbtack fact sheet", "operationId": "getFactsVsThumbtack", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }
    },
    "/facts/askbaily-vs-houzz.json": {
      "get": { "tags": ["facts"], "summary": "AskBaily vs Houzz fact sheet", "operationId": "getFactsVsHouzz", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }
    },
    "/facts/askbaily-vs-taskrabbit.json": {
      "get": { "tags": ["facts"], "summary": "AskBaily vs TaskRabbit fact sheet", "operationId": "getFactsVsTaskrabbit", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } }
    },
    "/feed/regulatory-updates.json": {
      "get": {
        "tags": ["regulatory"],
        "summary": "Regulatory change feed (JSON Feed v1.1)",
        "operationId": "getRegulatoryFeedJson",
        "responses": { "200": { "description": "20 source-linked regulatory changes with _askbaily namespace extension", "content": { "application/feed+json": { "schema": { "type": "object" } } } } }
      }
    },
    "/feed/regulatory-updates.xml": {
      "get": {
        "tags": ["regulatory"],
        "summary": "Regulatory change feed (RSS 2.0)",
        "operationId": "getRegulatoryFeedRss",
        "responses": { "200": { "description": "Subscribable by Feedly, Inoreader, journalist aggregators", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } }
      }
    },
    "/feed/content-freshness.json": {
      "get": {
        "tags": ["discovery"],
        "summary": "188-entry content freshness manifest",
        "operationId": "getContentFreshness",
        "responses": { "200": { "description": "Last-refreshed timestamps for top-tier pages", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "parameters": {
      "CitySlug": {
        "name": "city",
        "in": "path",
        "required": true,
        "description": "City slug from /data/cities.json (e.g. los-angeles, nyc, london, sydney). Spanish endpoint scope: los-angeles, miami, nyc, chicago, phoenix, houston, dallas, san-diego, las-vegas, sf.",
        "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }
      }
    },
    "schemas": {
      "Catalog": {
        "type": "object",
        "required": ["generatedAt", "license", "count", "items"],
        "properties": {
          "$schema": { "type": "string", "format": "uri" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "license": { "type": "string", "format": "uri" },
          "attribution": { "type": "string" },
          "namespace": { "type": "string" },
          "count": { "type": "integer", "minimum": 0 },
          "items": { "type": "array", "items": { "type": "object" } }
        }
      },
      "CitiesCatalog": {
        "allOf": [
          { "$ref": "#/components/schemas/Catalog" },
          {
            "type": "object",
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["slug", "name", "country"],
                  "properties": {
                    "slug": { "type": "string" },
                    "name": { "type": "string" },
                    "country": { "type": "string" },
                    "region": { "type": "string" },
                    "currency": { "type": "string" },
                    "primaryLocale": { "type": "string" }
                  }
                }
              }
            }
          }
        ]
      },
      "FaqIndex": {
        "type": "object",
        "required": ["generatedAt", "count", "endpoints"],
        "properties": {
          "$schema": { "type": "string", "format": "uri" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "license": { "type": "string", "format": "uri" },
          "count": { "type": "integer" },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["slug", "url", "count"],
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "country": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "count": { "type": "integer" }
              }
            }
          }
        }
      },
      "FaqCity": {
        "type": "object",
        "required": ["city", "regulator", "faqs"],
        "properties": {
          "$schema": { "type": "string", "format": "uri" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "license": { "type": "string", "format": "uri" },
          "city": {
            "type": "object",
            "properties": {
              "slug": { "type": "string" },
              "name": { "type": "string" },
              "country": { "type": "string" },
              "primaryLocale": { "type": "string" }
            }
          },
          "regulator": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "lookupUrl": { "type": "string" },
              "requiredClass": { "type": "string" }
            }
          },
          "relatedPages": {
            "type": "object",
            "properties": {
              "safety": { "type": "string", "format": "uri" },
              "safetyEN": { "type": "string", "format": "uri" },
              "safetyES": { "type": "string", "format": "uri" },
              "forPros": { "type": "string", "format": "uri" },
              "cost": { "type": "string", "format": "uri" }
            }
          },
          "faqs": {
            "type": "array",
            "minItems": 20,
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": ["q", "a", "category"],
              "properties": {
                "category": { "type": "string" },
                "q": { "type": "string" },
                "a": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}