{
  "schema_version": "v1",
  "name": "IVPools Engineering API",
  "description": "AI-native engineering platform for swimming pools, PV systems, saunas, and irrigation. Provides structured quote data, real-time pricing, and engineering specs via paid API endpoints.",
  "url": "https://ivpools.eu",
  "contact_email": "ivpools@abv.bg",
  "auth": {
    "type": "api_key",
    "header_name": "Authorization",
    "header_prefix": "Bearer",
    "alternative_header": "X-API-Key",
    "key_format": "av_live_<48_hex_chars>",
    "acquisition": "POST /api/agent-keys with body {agent_type, agent_name, email, plan}"
  },
  "endpoints": [
    {
      "path": "/api/v1/price",
      "method": "GET",
      "cost_usd": 0.001,
      "description": "Price lookup — returns product price, SKU, specs, availability",
      "params": {
        "category": "Required. One of: pump, filter, skimmer, nozzle, light, heatpump, robot, pv_panel, pv_inverter, pv_battery, sauna_stove, sauna_wood, irrigation_pipe, irrigation_emitter",
        "volume": "Optional number. For pumps/filters: m³/h. For heatpumps: kW. For inverters/batteries: kW/kWh",
        "recommended": "Optional boolean. If true, returns only recommended items"
      },
      "example_request": "GET /api/v1/price?category=pump&volume=20",
      "example_response": {
        "ok": true,
        "product": "Pool pump 1.1 kW (18 m³/h)",
        "sku": "PMP-11",
        "recommended": true,
        "price": 450,
        "currency": "EUR",
        "availability": "available",
        "specs": { "kw": 1.1, "flowM3h": 18 },
        "source": "ivpools"
      }
    },
    {
      "path": "/api/v1/quote",
      "method": "POST",
      "cost_usd": 0.005,
      "description": "Generate full engineering quote with Bill of Materials (BOM)",
      "body_schema": {
        "category": "pool (pv, sauna, irrigation coming soon)",
        "type": "skimmer | overflow_pool | infinity",
        "length": "number (m)",
        "width": "number (m)",
        "depth": "number (m)",
        "finish": "pvc_foil | ceramic | mosaic_standard | mosaic_premium (optional)",
        "heating": "none | heatpump | heat_exchanger | electric (optional)",
        "lights": "number (optional)",
        "robot": "boolean (optional)",
        "cover": "none | roller_electric | winter_steel (optional)",
        "region": "standard | mountain | coastal (optional)",
        "clientType": "Standard | VIP | Platinum (optional)"
      },
      "example_request": {
        "category": "pool",
        "type": "overflow_pool",
        "length": 8,
        "width": 4,
        "depth": 1.5,
        "location": "Burgas",
        "finish": "ceramic",
        "heating": "heatpump"
      }
    },
    {
      "path": "/api/v1/products",
      "method": "GET",
      "cost_usd": 0.002,
      "description": "List products in a category",
      "params": {
        "category": "Required — see /api/v1/price categories",
        "recommended": "Optional boolean"
      }
    },
    {
      "path": "/api/v1/repair",
      "method": "POST",
      "cost_usd": 0.004,
      "description": "Diagnose pool problems from natural language description",
      "body_schema": {
        "problem": "Required string — natural language description",
        "pool_type": "Optional: skimmer | overflow_pool | infinity",
        "volume": "Optional number (m³)",
        "age": "Optional number (years)",
        "symptoms": "Optional string[]: water_loss, cloudy_water, low_flow, algae, green_water, pump_failure"
      }
    }
  ],
  "pricing_plans": [
    { "code": "free", "name": "FREE", "monthly_usd": 0, "limits": "100 price + 10 quotes / month" },
    { "code": "developer", "name": "DEVELOPER", "monthly_usd": 10, "limits": "10k price + 1k quotes / month" },
    { "code": "agent", "name": "AGENT (PAYG)", "monthly_usd": 0, "limits": "Pay-as-you-go per call" },
    { "code": "enterprise", "name": "ENTERPRISE", "monthly_usd": 999, "limits": "Custom — contact sales" }
  ],
  "rate_limits": {
    "free": { "per_minute": 10, "per_day": 100 },
    "developer": { "per_minute": 60, "per_day": 5000 },
    "agent": { "per_minute": 120, "per_day": 50000 },
    "enterprise": { "per_minute": 600, "per_day": 500000 }
  },
  "response_headers": {
    "X-Request-Id": "Unique ID for each request — include in support requests",
    "X-RateLimit-Limit": "Max requests per minute for your plan",
    "X-RateLimit-Remaining": "Remaining requests in current minute",
    "X-Cost-USD": "Cost of this request in USD (for PAYG plans)"
  },
  "errors": {
    "401": "Missing or invalid API key",
    "402": "PAYG spending limit exceeded — add credit or upgrade plan",
    "403": "API key inactive, revoked, or scope denied",
    "404": "Resource not found",
    "429": "Rate limit exceeded — retry later",
    "500": "Internal server error — include X-Request-Id in support request"
  }
}