{
  "openapi": "3.1.0",
  "info": {
    "title": "ValveRide Flow Engine API",
    "version": "1.0.0",
    "description": "Keyed, stateless access to the ValveRide Flow diesel fuel-optimization engine. Send a truck profile, current position, destination, and your discount schedule; Flow routes the leg, discovers truck stops, prices them from its live retail diesel grid (7,500+ US truck stops), applies your discounts on net price with IFTA state-tax awareness, and returns where to stop and how many gallons to buy. A timed re-call with a drifted currentLocation is the replan. Also available as an MCP server at https://app.valverideflow.com/api/mcp (tools: optimize_fuel_plan, fuel_market_snapshot; developer API key or OAuth). Self-serve developer keys with $20 free credit: https://app.valverideflow.com/developers.",
    "contact": { "name": "ValveRide, LLC", "url": "https://valverideflow.com/contact" }
  },
  "servers": [{ "url": "https://app.valverideflow.com" }],
  "paths": {
    "/api/v1/engine/optimize": {
      "post": {
        "operationId": "optimizeFuelPlan",
        "summary": "Generate an optimized fuel plan for a truck route",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["truck", "currentFuelGallons", "currentLocation", "destination"],
                "properties": {
                  "truck": {
                    "type": "object",
                    "required": ["tankCapacityGallons", "mpgForPlanning"],
                    "properties": {
                      "tankCapacityGallons": { "type": "number", "description": "Total tank capacity in gallons, e.g. 240" },
                      "mpgForPlanning": { "type": "number", "description": "Planning miles per gallon, e.g. 6.5" },
                      "mpgLoaded": { "type": "number" },
                      "mpgEmpty": { "type": "number" },
                      "weightSensitive": { "type": "boolean" },
                      "ref": { "type": "string", "description": "Your identifier for this truck, echoed back" }
                    }
                  },
                  "currentFuelGallons": { "type": "number" },
                  "currentLocation": {
                    "description": "Truck position as {lat,lng} or a place string like \"Des Moines, IA\"",
                    "oneOf": [
                      { "type": "object", "required": ["lat", "lng"], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } },
                      { "type": "string" }
                    ]
                  },
                  "destination": {
                    "description": "Destination as {lat,lng} or a place string like \"Denver, CO\"",
                    "oneOf": [
                      { "type": "object", "required": ["lat", "lng"], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } },
                      { "type": "string" }
                    ]
                  },
                  "vendorRule": {
                    "type": "object",
                    "required": ["allowedVendors"],
                    "description": "STRICT vendor allowlist. When present, only stations of these brands are considered; the plan never falls back to other brands. Aliases are accepted (Love's / Loves / Love, Pilot / Flying J / PFJ, TA / Petro). If no compliant plan exists the response is 422 with code no_feasible_plan_under_vendor_rule. The 200 response echoes the enforced rule as vendorRule and the discounts that landed as appliedDiscounts.",
                    "properties": {
                      "allowedVendors": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 20,
                        "items": { "type": "string" },
                        "description": "Brand names the truck may fuel at, e.g. [\"Loves\"] or [\"Pilot\", \"Flying J\"]"
                      }
                    }
                  },
                  "discountSchedule": {
                    "type": "array",
                    "description": "Your negotiated fuel discounts, applied on top of live retail to optimize on net price. Send them in the same request as vendorRule so the discount applies to the allowed brand.",
                    "items": {
                      "type": "object",
                      "required": ["discountType", "discountAmount"],
                      "properties": {
                        "vendor": { "type": "string", "description": "Brand the discount applies to (aliases accepted, e.g. Loves / Love's); omit for all stations" },
                        "region": { "type": "string" },
                        "discountType": { "type": "string", "enum": ["CENTS_PER_GALLON", "PERCENTAGE"] },
                        "discountAmount": { "type": "number" }
                      }
                    }
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "remainingDriveHours": { "type": "number", "description": "HOS hours left; constrains reachable stops" },
                      "minGallonsPerStop": { "type": "number" },
                      "minFuelReserveGallons": { "type": "number" },
                      "destinationState": { "type": "string" },
                      "discoveryRadiusMiles": { "type": "number" },
                      "preferLargeTruckStops": { "type": "boolean" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Optimized plan: ranked stops, gallons per stop, net and tax-adjusted prices, estimated savings, engine version, the enforced vendorRule (when sent) and appliedDiscounts, and a Powered by Flow credit." },
          "400": { "description": "Invalid request; fields lists each problem (including a malformed vendorRule)." },
          "401": { "description": "Missing or invalid API key." },
          "422": { "description": "No usable plan. code is no_route, no_reachable_stops, no_priceable_stops, or no_feasible_plan_under_vendor_rule (a strict vendorRule left no compliant stop; Flow never substitutes another brand). Not billed." },
          "429": { "description": "Rate limit or monthly quota exceeded; headers carry retry guidance." },
          "503": { "description": "Degraded: daily engine cost budget reached; response includes a cached market teaser and Retry-After." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Partner engine API key, or a developer key / OAuth access token on the MCP surface. Self-serve keys: https://app.valverideflow.com/developers"
      }
    }
  }
}