{
  "openapi": "3.0.3",
  "info": {
    "title": "CarHauler247 Quotes API",
    "version": "v2.2.0",
    "description": "Server-to-server car shipping quotes API for US routes only, returning predicted carrier-side contract prices based on historical data, vehicle dimensions, seasonal migration patterns, geographic data, etc. This is the same real, battle-tested pricing engine we use for our own instant booking. [Get Your Key](/apiClient/keys) to get started - your first 1,000 calls are free, then it's pay-per-call. [See Pricing](/api-pricing)."
  },
  "servers": [
    { "url": "/api/public/v2" }
  ],
  "security": [
    { "bearerAuth": [] }
  ],
  "paths": {
    "/quote": {
      "get": {
        "summary": "Get a shipping quote",
        "description": "Billed at the quote rate ($0.0042/call) - see [Pricing](/api-pricing). This is the expensive call; the car and ZIP lookup endpoints below are much cheaper ($0.0001/call).",
        "operationId": "getQuote",
        "parameters": [
          { "name": "fromZip", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Origin ZIP code (5 digits)" },
          { "name": "toZip", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Destination ZIP code (5 digits)" },
          {
            "name": "vehicleType", "in": "query", "required": false,
            "schema": {
              "type": "string",
              "enum": ["sedan", "suv", "pickup", "truck", "van", "minivan", "hatchback", "convertible", "coupe", "wagon"],
              "default": "sedan"
            },
            "description": "Vehicle type (unrecognized values fall back to sedan pricing)"
          },
          { "name": "isOperational", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Whether the vehicle runs and drives" },
          { "name": "shippingDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Desired pickup date (YYYY-MM-DD). Defaults to 7 days from today if omitted. Must not be in the past. Snowbird lane prices change ~7%/week during seasonal ramp-up." },
          { "name": "trimId", "in": "query", "required": false, "schema": { "type": "integer", "example": 5001 }, "description": "Trim id from /car/trims, for precise per-vehicle pricing. Wins over vehicleType when both are given - adds a dimension-based price adjustment on top of the usual body-style pricing." }
        ],
        "responses": {
          "200": {
            "description": "Quote computed (success:false with a message means a validation/pricing failure, not a transport error - see the message field)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } }
          },
          "401": {
            "description": "Missing, invalid, or revoked API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "402": {
            "description": "Free call allowance used up - billing needs to be set up to continue",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/car/makes": {
      "get": {
        "summary": "List car makes",
        "description": "Billed at the cheap lookup rate ($0.0001/call), not the quote rate - see [Pricing](/api-pricing).",
        "operationId": "getCarMakes",
        "responses": {
          "200": {
            "description": "All car makes",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarMake" } } } }
          },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "402": { "description": "Free call allowance used up - billing needs to be set up to continue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/car/models": {
      "get": {
        "summary": "List models for a make",
        "description": "Billed at the cheap lookup rate ($0.0001/call), not the quote rate - see [Pricing](/api-pricing).",
        "operationId": "getCarModels",
        "parameters": [
          { "name": "makeId", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Make id from /car/makes" }
        ],
        "responses": {
          "200": {
            "description": "Models for the given make",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarModel" } } } }
          },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "402": { "description": "Free call allowance used up - billing needs to be set up to continue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/car/years": {
      "get": {
        "summary": "List years available for a model",
        "description": "Billed at the cheap lookup rate ($0.0001/call), not the quote rate - see [Pricing](/api-pricing).",
        "operationId": "getCarYears",
        "parameters": [
          { "name": "modelId", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Model id from /car/models" }
        ],
        "responses": {
          "200": {
            "description": "Years available for the given model",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "integer" }, "example": [2022, 2023, 2024] } } }
          },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "402": { "description": "Free call allowance used up - billing needs to be set up to continue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/car/trims": {
      "get": {
        "summary": "List trims for a model and year",
        "description": "Billed at the cheap lookup rate ($0.0001/call), not the quote rate - see [Pricing](/api-pricing).",
        "operationId": "getCarTrims",
        "parameters": [
          { "name": "modelId", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Model id from /car/models" },
          { "name": "year", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Year from /car/years" }
        ],
        "responses": {
          "200": {
            "description": "Trims available for the given model and year",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CarTrim" } } } }
          },
          "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "402": { "description": "Free call allowance used up - billing needs to be set up to continue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/zipcode/search": {
      "get": {
        "summary": "Search ZIP codes by prefix",
        "description": "Billed at the cheap lookup rate ($0.0001/call), not the quote rate - see [Pricing](/api-pricing).",
        "operationId": "searchZipCodes",
        "parameters": [
          { "name": "zipPrefix", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 5, "pattern": "^\\d+$" }, "description": "3-5 digit ZIP code prefix" }
        ],
        "responses": {
          "200": {
            "description": "Up to 8 matches, largest population first",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ZipCodeResult" } } } }
          },
          "401": {
            "description": "Missing, invalid, or revoked API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          },
          "402": {
            "description": "Free call allowance used up - billing needs to be set up to continue",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Get a key at https://carhauler247.com/apiClient/keys"
      }
    },
    "schemas": {
      "QuoteResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "message": { "type": "string", "nullable": true, "description": "Only present when success is false - explains why the call failed" },
          "quote": { "$ref": "#/components/schemas/QuoteDetails", "nullable": true }
        },
        "example": {
          "success": true,
          "quote": {
            "price": 1189,
            "distance": 2796,
            "drivingTime": "4 days and 7 hours drive",
            "vehicleType": "sedan",
            "carrier": "open",
            "operational": true
          }
        }
      },
      "QuoteDetails": {
        "type": "object",
        "properties": {
          "price": { "type": "integer" },
          "distance": { "type": "integer" },
          "drivingTime": { "type": "string" },
          "vehicleType": { "type": "string" },
          "carrier": { "type": "string" },
          "operational": { "type": "boolean" }
        }
      },
      "CarMake": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Toyota" }
        }
      },
      "CarModel": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 101 },
          "name": { "type": "string", "example": "Camry" }
        }
      },
      "CarTrim": {
        "type": "object",
        "description": "Only id and name are exposed - dimensions/weight are pricing inputs used internally by getQuote's trimId param, not returned here.",
        "properties": {
          "id": { "type": "integer", "example": 5001 },
          "name": { "type": "string", "example": "LE" }
        }
      },
      "ZipCodeResult": {
        "type": "object",
        "properties": {
          "zip": { "type": "string", "example": "90001" },
          "city": { "type": "string", "example": "Los Angeles" },
          "state": { "type": "string", "example": "CA" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  }
}