{
  "openapi": "3.1.0",
  "info": {
    "title": "franchisedata.io API",
    "version": "1.0.0",
    "description": "Institutional franchise restaurant intelligence gateway providing location data, POS hardware fingerprints, Item 19 unit economics, multi-unit operator trees, real-time news wire, and Model Context Protocol (MCP) server for autonomous AI coding agents."
  },
  "servers": [
    {
      "url": "https://franchisedata.io",
      "description": "Production gateway"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "paths": {
    "/api/brands": {
      "get": {
        "summary": "List all franchise brands",
        "description": "Returns full catalog of all 500 indexed franchise chains with categories, store counts, primary POS hardware, and endpoint prices.",
        "responses": {
          "200": { "description": "OK" }
        }
      }
    },
    "/api/brands/{brand}": {
      "get": {
        "summary": "Get brand profile and sync recency",
        "description": "Commercial summary, store count, POS breakdown, and real-time ingestion timestamps (last_synced_at, last_synced_iso).",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Brand slug (e.g. mcdonalds, starbucks, wendys)" }
        ],
        "responses": {
          "200": { "description": "OK" },
          "404": { "description": "Brand not found" }
        }
      }
    },
    "/api/brands/{brand}/locations": {
      "get": {
        "summary": "Search brand locations",
        "description": "Filter store locations by city, state, postal code, drive-thru flag, or radial distance. Price: $0.003 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Two-letter US state code" },
          { "name": "city", "in": "query", "schema": { "type": "string" }, "description": "City name" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Postal zip code" },
          { "name": "drive_thru", "in": "query", "schema": { "type": "string" }, "description": "Set to 1 or true for drive-thru only" },
          { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Radial center latitude" },
          { "name": "lng", "in": "query", "schema": { "type": "number" }, "description": "Radial center longitude" },
          { "name": "radius_miles", "in": "query", "schema": { "type": "number", "default": 25 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": { "description": "Locations returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/store/{storeId}/status": {
      "get": {
        "summary": "Check real-time store operating status",
        "description": "Calculates whether store is currently open in its local timezone, operating hours, minutes to close, and holiday exceptions. Price: $0.002 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Status returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/store/{storeId}/tech-stack": {
      "get": {
        "summary": "Inspect in-store POS and technology stack",
        "description": "Identifies POS hardware (Toast, NCR Aloha, Oracle Simphony, Brink), KDS, digital ordering middleware, and payment gateways. Price: $0.002 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Tech stack returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/store/{storeId}/delivery": {
      "get": {
        "summary": "Inspect third-party delivery marketplace shelf",
        "description": "Direct marketplace deep links (DoorDash, Uber Eats, Grubhub), platform ratings, and menu price markup telemetry. Price: $0.002 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "storeId", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Delivery shelf returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/operators": {
      "get": {
        "summary": "Query multi-unit franchisee operators",
        "description": "Returns franchisee operating LLCs, parent holding groups (e.g. Flynn Group, Sun Holdings), executive contacts, and portfolio unit counts. Price: $0.004 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Operators returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/fdd": {
      "get": {
        "summary": "Get FDD Item 19 unit economics",
        "description": "Statutory Item 19 financial disclosure benchmarks: Median AUV, top/bottom quartile revenue, royalty %, ad fund %, and Item 7 initial investment ranges. Price: $0.004 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "FDD benchmarks returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/fdd/compare": {
      "get": {
        "summary": "Side-by-side comparative FDD Item 19 benchmarks",
        "description": "Compare Item 19 AUV mean/median, quartiles, royalty %, ad fund %, and initial investment across multiple chains in a single query. Price: $0.020 in USDC.",
        "parameters": [
          { "name": "brands", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated brand slugs (e.g. mcdonalds,wendys,tacobell)" }
        ],
        "responses": {
          "200": { "description": "Comparative benchmarks returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/brands/{brand}/changes": {
      "get": {
        "summary": "Track store openings and closures",
        "description": "Real-time verified delta feed of new store openings, permanent closures, relocations, and re-branding events. Price: $0.003 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["opening", "closure", "relocation"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 } }
        ],
        "responses": {
          "200": { "description": "Fleet changes returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/search/near": {
      "get": {
        "summary": "Radial cross-brand restaurant search",
        "description": "Cross-brand radial geospatial search returning all open franchise restaurants within a radius of latitude/longitude coordinates. Price: $0.005 in USDC.",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Center latitude" },
          { "name": "lng", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Center longitude" },
          { "name": "radius_miles", "in": "query", "schema": { "type": "number", "default": 10 } },
          { "name": "category", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Nearby locations returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/news": {
      "get": {
        "summary": "Real-time franchise news wire",
        "description": "24/7 institutional wire tracking regulatory filings, franchisor distress, franchisee litigation, wage mandates, M&A rollups, and fleet expansions across all 500 chains.",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "distress, litigation, labor_wages, leadership, ma_rollup, sec_filing, fdd_update, tech_stack, pricing, expansion, investors" },
          { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Brand slug or name filter" },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keyword search across headlines and content" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": { "description": "News wire returned" }
        }
      }
    },
    "/api/stocks": {
      "get": {
        "summary": "Forbes Global Top 200 equities and real-time tape",
        "description": "Live consolidated quote tape tracking public restaurant equities, private equity rollups, systemwide sales, public market caps, power scores, and live price tickers.",
        "responses": {
          "200": { "description": "Equities tape returned" }
        }
      }
    },
    "/api/export/brands/{brand}": {
      "get": {
        "summary": "Bulk fleet data export",
        "description": "Download full RFC 4180 compliant CSV or GeoJSON datasets of an entire brand's fleet enriched with in-store POS tech stacks and franchisee LLCs. Price: $0.050 in USDC.",
        "parameters": [
          { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["csv", "json"], "default": "csv" } },
          { "name": "state", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Dataset returned" },
          "402": { "description": "Payment Required" }
        },
        "security": [{ "bearerAuth": [] }, { "x402Auth": [] }]
      }
    },
    "/api/credits/balance": {
      "get": {
        "summary": "Check API credit balance",
        "description": "FREE. Inspect remaining credit balance on your fc_live_... API key.",
        "responses": {
          "200": { "description": "Balance returned" },
          "401": { "description": "Invalid API key" }
        },
        "security": [{ "bearerAuth": [] }]
      }
    },
    "/api/credits/topup": {
      "post": {
        "summary": "Mint API key or top up prepaid credits",
        "description": "Top up existing fc_live_... key or mint a new one with prepaid USDC balance.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount_usd": { "type": "number", "minimum": 1.0 },
                  "api_key": { "type": "string" }
                },
                "required": ["amount_usd"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Credits applied or key minted" }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "summary": "Model Context Protocol (MCP) streamable HTTP endpoint",
        "description": "JSON-RPC 2.0 remote MCP gateway supporting 17 live tools for Claude Code, Cursor, and autonomous agents.",
        "responses": {
          "200": { "description": "JSON-RPC response" }
        },
        "security": [{ "bearerAuth": [] }]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fc_live_*"
      },
      "x402Auth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment",
        "description": "Signed stateless on-chain USDC transfer authorization (RFC 402)"
      }
    }
  }
}