{
  "openapi": "3.0.3",
  "info": {
    "title": "Chronovisor API",
    "version": "v1",
    "description": "Probability intelligence from blended prediction markets (Polymarket, Manifold, Kalshi). Returns a structured forecast with a probability index, confidence, direction, research-grade statistics, and a plain-English AI interpretation. Informational only — not financial, legal, or betting advice.",
    "contact": { "name": "Voynich Tech" }
  },
  "servers": [
    { "url": "https://chronovisor-luisochoasap-2007s-projects.vercel.app", "description": "Production" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "service": { "type": "string" },
                    "routes": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/forecast/search": {
      "post": {
        "summary": "Generate a forecast for a topic",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "example": "Will Bitcoin reach $150k in 2026?" },
                  "persona": {
                    "type": "string",
                    "enum": ["regular", "technical", "founder", "trader"],
                    "default": "regular",
                    "description": "Tone of the interpretation."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A structured forecast readout",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } }
            }
          }
        }
      }
    },
    "/api/v1/forecast/history": {
      "get": {
        "summary": "Snapshot history for a topic",
        "parameters": [
          { "name": "topic", "in": "query", "required": true, "schema": { "type": "string" }, "example": "bitcoin" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Stored forecast snapshots over time (for trend and calibration)",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ForecastResponse": {
        "type": "object",
        "properties": {
          "engine_version": { "type": "string" },
          "generated_at": { "type": "string", "format": "date-time" },
          "topic": {
            "type": "object",
            "properties": {
              "canonical": { "type": "string" },
              "display_name": { "type": "string" },
              "category": { "type": "string" }
            }
          },
          "probability_index": {
            "type": "object",
            "properties": {
              "value": { "type": "number", "description": "0-100 liquidity-weighted probability" },
              "label": { "type": "string", "enum": ["low", "medium", "high"] },
              "basis": { "type": "string" }
            }
          },
          "confidence": { "type": "object", "properties": { "value": { "type": "number" }, "label": { "type": "string" } } },
          "direction_compass": { "type": "object", "properties": { "value": { "type": "string", "enum": ["up", "down", "sideways", "nowhere"] } } },
          "statistics": {
            "type": "object",
            "description": "Research-grade statistics across the markets.",
            "properties": {
              "n_markets": { "type": "integer" },
              "n_sources": { "type": "integer" },
              "weighted_mean_probability": { "type": "number" },
              "std_dev": { "type": "number" },
              "consensus": { "type": "string", "enum": ["tight", "moderate", "wide", "insufficient"] },
              "dispersion_band_95": { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" }, "label": { "type": "string" } } },
              "methodology": { "type": "array", "items": { "type": "string" } },
              "limitations": { "type": "array", "items": { "type": "string" } }
            }
          },
          "AI_interpretation": {
            "type": "object",
            "properties": {
              "headline": { "type": "string" },
              "summary": { "type": "string" },
              "confidence_explanation": { "type": "string" },
              "generator": { "type": "string", "enum": ["deterministic_template", "ai_model"] }
            }
          },
          "markets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "source": { "type": "string" },
                "probability": { "type": "number" },
                "volume": { "type": "number" }
              }
            }
          },
          "sources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" } } } },
          "disclaimers": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}