{"openapi":"3.0.3","info":{"title":"IVPools Engineering API","description":"AI-native engineering platform for swimming pools, PV systems, saunas, and irrigation. All endpoints require API key authentication via Authorization: Bearer av_live_xxx or X-API-Key header. URL query auth (?key=) is disabled for security.","version":"2.0.0","contact":{"email":"ivpools@abv.bg"},"license":{"name":"Proprietary","url":"https://ivpools.eu/legal"}},"servers":[{"url":"https://ivpools.eu","description":"Production"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use 'Bearer av_live_xxx'. Get your API key via POST /api/agent-keys."},"XApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative: X-API-Key: av_live_xxx"}},"headers":{"XRequestId":{"description":"Unique request ID for support/troubleshooting","schema":{"type":"string"}},"XRateLimitLimit":{"description":"Max requests per minute for your plan","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Remaining requests in current minute","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}},"XCostUSD":{"description":"Cost of this request in USD (for PAYG plans)","schema":{"type":"number"}},"XAPIVersion":{"description":"API version","schema":{"type":"string"}},"XProcessingTime":{"description":"Server processing time in milliseconds","schema":{"type":"integer"}}}},"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Pricing","description":"Price + product lookups"},{"name":"Engineering","description":"Quote + optimization operations"},{"name":"Repair","description":"Pool repair diagnosis"},{"name":"Inventory","description":"Real-time stock availability"},{"name":"MCP","description":"Model Context Protocol for AI agents"},{"name":"Billing","description":"Stripe + USDC payment rails"},{"name":"Discovery","description":"AI discovery files (no auth)"}],"paths":{"/api/v1/price":{"get":{"tags":["Pricing"],"summary":"Price lookup (real DB)","description":"Returns product price + specs + real availability from database. Cost: $0.001 USD per call.","parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string"}},{"name":"volume","in":"query","required":false,"schema":{"type":"number"}},{"name":"recommended","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"region","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product found"},"404":{"description":"No product matching criteria"}}}},"/api/v1/quote":{"post":{"tags":["Engineering"],"summary":"Generate engineering quote (unified engine)","description":"Generates full BOM via unified AQUA VITAE engine. Returns confidence field indicating whether human engineer review is required. Cost: $0.005 USD per call. Supports Idempotency-Key header for safe retries.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Unique key — same key returns same quote, no double charge"}],"responses":{"200":{"description":"Quote generated"}}}},"/api/v1/optimize":{"post":{"tags":["Engineering"],"summary":"Engineering Optimization API","description":"Finds the best pool configuration within budget + constraints. Returns multiple candidates ranked by score. Cost: $0.020 USD per call.","responses":{"200":{"description":"Optimization result with recommended candidate"}}}},"/api/v1/products":{"get":{"tags":["Pricing"],"summary":"List products in category","description":"Returns products with real prices + stock levels from DB. Cost: $0.002 USD per call.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"recommended","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of products with stock info"}}}},"/api/v1/repair":{"post":{"tags":["Repair"],"summary":"Diagnose pool problems","description":"Returns probability-ranked causes + recommended tests + estimated repair cost range. Cost: $0.004 USD per call.","responses":{"200":{"description":"Diagnosis"}}}},"/api/v1/availability":{"get":{"tags":["Inventory"],"summary":"Check real inventory availability","description":"Returns actual stock quantity, lead time, warehouse location. Cost: $0.001 USD per call.","parameters":[{"name":"sku","in":"query","required":true,"schema":{"type":"string"}},{"name":"region","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Availability info"}}}},"/api/mcp":{"post":{"tags":["MCP"],"summary":"MCP JSON-RPC 2.0 endpoint","description":"Streamable HTTP transport. Session management via Mcp-Session-Id header. All tools/call go through withMetering (auth + rate-limit + cost + metering). Tools: get_price, list_products, create_quote, diagnose_repair, calculate_pool, check_availability, optimize_solution.","responses":{"200":{"description":"JSON-RPC response"}}},"get":{"tags":["MCP"],"summary":"MCP server info (discovery)","description":"Public endpoint — no auth required. Returns server info, tools list, pricing, capabilities.","responses":{"200":{"description":"Server info"}}}},"/api/agent-keys":{"post":{"tags":["Authentication"],"summary":"Create API key (signup)","description":"Self-service API key creation. Rate-limited: max 5 signups per IP per hour, max 3 active keys per email.","responses":{"200":{"description":"API key created (plain key shown once)"}}},"get":{"tags":["Authentication"],"summary":"View API key details + usage","description":"Returns key info + plan + 24h usage stats + recent events. Auth: header only.","responses":{"200":{"description":"Key details + usage"}}},"delete":{"tags":["Authentication"],"summary":"Revoke API key","description":"Soft delete — marks key as inactive. Auth: header only.","responses":{"200":{"description":"Key revoked"}}}},"/api/billing/plans":{"get":{"tags":["Billing"],"summary":"List pricing plans","description":"Public — no auth required. Returns all tariff plans with quotas + PAYG pricing.","responses":{"200":{"description":"Plans list"}}}},"/api/billing/stripe/create-checkout":{"post":{"tags":["Billing"],"summary":"Create Stripe Checkout session","description":"Creates Stripe Checkout URL for subscription or one-time credit purchase. Primary payment rail.","responses":{"200":{"description":"Checkout URL"}}}},"/api/billing/stripe/webhook":{"post":{"tags":["Billing"],"summary":"Stripe webhook receiver","description":"Receives Stripe events. Verifies signature, updates Credit + BillingEvent tables.","responses":{"200":{"description":"Webhook acknowledged"}}}},"/api/wallet/charge":{"post":{"tags":["Billing"],"summary":"Verify USDC payment (MetaMask)","description":"Secondary payment rail. Verifies MetaMask USDC txHash on Base L2, adds credit to API key.","responses":{"200":{"description":"Credit added"}}}},"/api/admin/agent-commerce":{"get":{"tags":["Admin"],"summary":"Admin dashboard data","description":"Returns total revenue, all API keys, agents, recent events. Requires admin password.","parameters":[{"name":"password","in":"query","required":true,"schema":{"type":"string"},"description":"ADMIN_PASSWORD from .env"}],"responses":{"200":{"description":"Dashboard data"}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"AI discovery file (llms.txt format)","description":"Standard llms.txt — describes API + pricing for AI systems. No auth.","responses":{"200":{"description":"Plain text"}}}},"/.well-known/ai-plugin.json":{"get":{"tags":["Discovery"],"summary":"AI plugin manifest","description":"ChatGPT plugin schema. No auth.","responses":{"200":{"description":"JSON manifest"}}}}}}