{
  "openapi": "3.1.0",
  "info": {
    "title": "CarValuator Valuation API",
    "version": "1.0.0",
    "description": "White-label used-car valuation as a REST API. Send a VIN, a make/model, or a photo and receive a structured resale valuation (low / mid / high plus source breakdown and insights) that you can render in your own product under your own brand.\n\nAuthenticate with a per-client API key: `Authorization: Bearer cvk_...`. Sandbox keys (`cvk_test_...`) return sample data for free so you can build your integration before going live.",
    "contact": {
      "name": "CarValuator",
      "url": "https://carvaluator.app",
      "email": "contact@carvaluator.app"
    }
  },
  "servers": [
    {
      "url": "https://api.carvaluator.app",
      "description": "Production"
    }
  ],
  "security": [
    { "bearerAuth": [] }
  ],
  "paths": {
    "/v1/valuation": {
      "post": {
        "summary": "Value a vehicle",
        "description": "Returns a resale valuation for one vehicle. Provide at least one of: `vin`, `make`+`model`, or `photoBase64`. Successful calls count against your monthly quota (sandbox keys never bill).",
        "operationId": "createValuation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ValuationRequest" },
              "examples": {
                "byVin": {
                  "summary": "By VIN",
                  "value": { "vin": "1HGCM82633A004352", "lang": "en" }
                },
                "byDetails": {
                  "summary": "By make/model",
                  "value": {
                    "make": "Honda",
                    "model": "Accord",
                    "year": 2015,
                    "mileage": 82000,
                    "condition": "clean",
                    "lang": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A valuation.",
            "headers": {
              "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per minute." },
              "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." },
              "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the rate window resets." },
              "X-Quota-Limit": { "schema": { "type": "integer" }, "description": "Monthly quota (0 = uncapped)." },
              "X-Quota-Used": { "schema": { "type": "integer" }, "description": "Calls used this month." },
              "X-Quota-Remaining": { "schema": { "type": "integer" }, "description": "Calls left this month." }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Valuation" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": {
            "description": "Monthly quota exceeded — upgrade the plan or contact sales.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "413": { "$ref": "#/components/responses/Error" },
          "429": {
            "description": "Rate limited. Honor the Retry-After header.",
            "headers": {
              "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "500": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "cvk_live_... or cvk_test_...",
        "description": "Your CarValuator API key. Also accepted as the header `x-api-key`."
      }
    },
    "schemas": {
      "ValuationRequest": {
        "type": "object",
        "description": "Provide at least one identifying input.",
        "properties": {
          "vin": { "type": "string", "description": "17-character VIN.", "example": "1HGCM82633A004352" },
          "make": { "type": "string", "example": "Honda" },
          "model": { "type": "string", "example": "Accord" },
          "year": { "type": "integer", "example": 2015 },
          "mileage": { "type": "integer", "description": "Odometer in miles.", "example": 82000 },
          "condition": { "type": "string", "description": "Free text, e.g. clean, fair, rough.", "example": "clean" },
          "photoBase64": { "type": "string", "description": "Base64 of a photo of the car or its VIN plate (optional)." },
          "photoMimeType": { "type": "string", "example": "image/jpeg" },
          "lang": { "type": "string", "enum": ["en", "es"], "default": "en", "description": "Language for the insights/recommendation text." }
        }
      },
      "Valuation": {
        "type": "object",
        "properties": {
          "identified": { "type": "boolean", "description": "Whether the vehicle was recognized." },
          "car": {
            "type": "object",
            "properties": {
              "year": { "type": "integer" },
              "make": { "type": "string" },
              "model": { "type": "string" },
              "mileage": { "type": "integer" },
              "condition": { "type": "string" }
            }
          },
          "value": {
            "type": "object",
            "properties": {
              "low": { "type": "integer", "description": "Conservative resale estimate." },
              "mid": { "type": "integer", "description": "Most likely resale value." },
              "high": { "type": "integer", "description": "Optimistic resale estimate." },
              "currency": { "type": "string", "example": "USD" }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "price": { "type": "integer" },
                "note": { "type": "string" }
              }
            }
          },
          "marketInsights": { "type": "string" },
          "recommendation": { "type": "string" },
          "requestId": { "type": "string", "description": "Correlation id for support/audit.", "example": "req_8f2c1a0b9d3e" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Machine-readable code, e.g. unauthorized, rate_limited, quota_exceeded." },
          "message": { "type": "string" },
          "requestId": { "type": "string" }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}