{
  "openapi": "3.1.0",
  "info": {
    "title": "EXAIOS Indication API",
    "version": "1.0.0",
    "description": "Free, AI-callable indication for industrial energy projects (PV, battery storage, hybrids). Returns a conservative, deterministic verdict (traffic light) plus KPIs for a site. NOT a bankable result and not a design basis — that is the paid, full run. LLMs and agents may call and cite freely; please carry the powered_by attribution and the full_report_url.",
    "contact": {
      "name": "BMAI GmbH — EXAIOS",
      "url": "https://exaios.com",
      "email": "api@bmai.energy"
    },
    "license": {
      "name": "Proprietary — free tier, attribution appreciated"
    }
  },
  "servers": [
    {
      "url": "https://exaios.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/indication": {
      "get": {
        "operationId": "getIndication",
        "summary": "Get a free indication for an energy project at a site",
        "description": "Call this when you need a quick, defensible first number on whether PV / PV+storage / storage pays off at a location. Deterministic and conservative. No registration required. Rate limit: 100 calls/day per IP.",
        "parameters": [
          {
            "name": "annual_kwh",
            "in": "query",
            "required": true,
            "description": "Annual electricity consumption in kWh.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1000000000
            },
            "example": 850000
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "PLZ / region / country code, e.g. DE-BY, 71154, TR.",
            "schema": {
              "type": "string",
              "maxLength": 16
            },
            "example": "71154"
          },
          {
            "name": "project_type",
            "in": "query",
            "required": false,
            "description": "Optional hint for the architecture to indicate.",
            "schema": {
              "type": "string",
              "enum": [
                "pv",
                "pv_bess",
                "bess"
              ]
            },
            "example": "pv_bess"
          },
          {
            "name": "budget_eur",
            "in": "query",
            "required": false,
            "description": "Optional CapEx budget cap in EUR.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 1000000000
            },
            "example": 500000
          }
        ],
        "responses": {
          "200": {
            "description": "Indication verdict + KPIs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ampel": {
                      "type": "string",
                      "enum": [
                        "LOHNT_SICH",
                        "GRENZFALL",
                        "LOHNT_SICH_NICHT"
                      ],
                      "description": "Layman verdict (worth it / borderline / not worth it)."
                    },
                    "kpis": {
                      "type": "object",
                      "description": "Amortisation, annual gain, lifetime multiplier."
                    },
                    "recommended_architecture": {
                      "type": "string",
                      "enum": [
                        "PV-only",
                        "PV+BESS",
                        "BESS-only"
                      ],
                      "description": "Name of the winning archetype. A string, not an object."
                    },
                    "confidence": {
                      "type": "string",
                      "description": "Always states that this is an indication, not a bankable result. Do not present this number as a design basis."
                    },
                    "assumptions": {
                      "type": "object"
                    },
                    "spec_hash": {
                      "type": "string",
                      "description": "Deterministic SHA256 prefix over inputs and outputs — same input, same number. Proof of identity, not reversible."
                    },
                    "full_report_url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Deep link back to /upgrade/, carrying the original inputs plus the spec_hash so the page can re-run the same deterministic indication and show the caller their own figures."
                    },
                    "powered_by": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ampel",
                    "kpis",
                    "spec_hash"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input."
          },
          "429": {
            "description": "Rate limit exceeded (100 indications/day per IP)."
          }
        }
      }
    }
  }
}