{
  "openapi": "3.1.0",
  "info": {
    "title": "QUANTUM Pinui-Binui Discovery API",
    "version": "1.0.0",
    "description": "Read-only public API for AI agents and Custom GPTs to query QUANTUM's live database of Israeli pinui-binui compounds, mispricing opportunities, and statutory stage tracking. Data regenerated hourly from the QUANTUM analyzer database. License: CC-BY-4.0.",
    "contact": { "name": "QUANTUM", "url": "https://u-r-quantum.com", "email": "hello@u-r-quantum.com" },
    "license": { "name": "CC-BY-4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "servers": [
    { "url": "https://pinuy-binuy-analyzer-production.up.railway.app", "description": "Production (Railway)" }
  ],
  "paths": {
    "/opportunities.json": {
      "get": {
        "operationId": "listMispricedCompounds",
        "summary": "List top mispriced Israeli pinui-binui compounds ranked by QUANTUM Mispricing Score",
        "description": "Returns the current top compounds ranked by QUANTUM Mispricing Score (premium_gap times active_listings times statutory_certainty). Use this to find pinui-binui compounds where the secondary-market price has not yet repriced to the statutory stage.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 100 }, "description": "Max compounds to return." }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitiesResponse" } } } }
        }
      }
    },
    "/changelog.json": {
      "get": {
        "operationId": "listStatutoryChanges",
        "summary": "Recent statutory stage changes (last N days)",
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": {} } }
        }
      }
    },
    "/feed.atom": {
      "get": {
        "operationId": "getOpportunitiesFeed",
        "summary": "Atom feed of top mispriced pinui-binui compounds",
        "responses": { "200": { "description": "OK", "content": { "application/atom+xml": {} } } }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "LLM-readable summary with live mispricing table",
        "responses": { "200": { "description": "OK", "content": { "text/markdown": {} } } }
      }
    }
  },
  "components": {
    "schemas": {
      "OpportunitiesResponse": {
        "type": "object",
        "properties": {
          "generated_at": { "type": "string", "format": "date-time" },
          "data_as_of":   { "type": "string", "format": "date-time" },
          "coverage": {
            "type": "object",
            "properties": {
              "total_compounds":      { "type": "integer" },
              "tracked_compounds":    { "type": "integer" },
              "high_iai_compounds":   { "type": "integer" },
              "active_listings_total":{ "type": "integer" },
              "transactions_12mo":    { "type": "integer" }
            }
          },
          "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }
        }
      },
      "Opportunity": {
        "type": "object",
        "properties": {
          "rank":           { "type": "integer" },
          "compound_id":    { "type": "integer" },
          "slug":           { "type": "string" },
          "name":           { "type": "string" },
          "city":           { "type": "string" },
          "neighborhood":   { "type": "string" },
          "statutory_stage":{ "type": "string", "enum": ["permit","approved","deposited","construction","declared","planning","pre_deposit","unknown"] },
          "statutory_stage_he": { "type": "string" },
          "plan_number":    { "type": "string" },
          "developer":      { "type": "string" },
          "scoring": {
            "type": "object",
            "properties": {
              "iai_score":            { "type": "integer" },
              "mispricing_score":     { "type": "integer" },
              "premium_gap_pct":      { "type": "number" },
              "actual_premium_pct":   { "type": "number" }
            }
          },
          "market": {
            "type": "object",
            "properties": {
              "active_listings":         { "type": "integer" },
              "avg_asking_price_nis":    { "type": "number" },
              "min_asking_price_nis":    { "type": "number" },
              "max_asking_price_nis":    { "type": "number" },
              "avg_area_sqm":            { "type": "number" },
              "avg_rooms":               { "type": "number" },
              "avg_price_per_sqm_nis":   { "type": "number" }
            }
          },
          "detail_url":     { "type": "string", "format": "uri" }
        }
      }
    }
  }
}