{
  "openapi": "3.1.0",
  "info": {
    "title": "CarChat API",
    "version": "1.0.0",
    "description": "Live dealership inventory with buyer inquiry submission. Reads are free, open CORS, no API key. Built for AI agents shopping on behalf of car buyers. Human docs: https://carchat.io/agents"
  },
  "servers": [{ "url": "https://carchat.io" }],
  "paths": {
    "/api/v1/inventory": {
      "get": {
        "operationId": "searchInventory",
        "summary": "Search live vehicle inventory across all dealerships",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text query in plain English, e.g. 'black suv under 30k'. Parsed into the structured filters below; explicit parameters win over parsed ones." },
          { "name": "make", "in": "query", "schema": { "type": "string" }, "example": "Audi" },
          { "name": "model", "in": "query", "schema": { "type": "string" }, "example": "Q5" },
          { "name": "body", "in": "query", "schema": { "type": "string", "enum": ["suv", "truck", "sedan", "coupe", "convertible", "hatchback", "wagon", "minivan", "van"] } },
          { "name": "color", "in": "query", "schema": { "type": "string" }, "example": "black" },
          { "name": "condition", "in": "query", "schema": { "type": "string", "enum": ["new", "used"] } },
          { "name": "minPrice", "in": "query", "schema": { "type": "integer" }, "description": "USD" },
          { "name": "maxPrice", "in": "query", "schema": { "type": "integer" }, "description": "USD" },
          { "name": "minYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "maxYear", "in": "query", "schema": { "type": "integer" } },
          { "name": "maxMileage", "in": "query", "schema": { "type": "integer" } },
          { "name": "dealer", "in": "query", "schema": { "type": "string" }, "description": "Dealer id or slug from /api/v1/dealers" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["price-asc", "price-desc", "year-desc", "miles-asc"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Matching vehicles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "offset": { "type": "integer" },
                    "results": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } },
                    "next": { "type": ["string", "null"], "description": "URL of the next page, or null" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/vehicles/{id}": {
      "get": {
        "operationId": "getVehicle",
        "summary": "Get one vehicle by VIN or listing id",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "VIN when known, otherwise the listing id returned by searchInventory" }],
        "responses": {
          "200": { "description": "The vehicle, including a ready-to-use inquiry template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } },
          "404": { "description": "Not found; it may have sold. Inventory refreshes daily." }
        }
      }
    },
    "/api/v1/dealers": {
      "get": {
        "operationId": "listDealers",
        "summary": "List dealerships with live inventory on CarChat",
        "responses": {
          "200": {
            "description": "Dealerships",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "dealers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "city": { "type": ["string", "null"] },
                          "state": { "type": ["string", "null"] },
                          "vehicleCount": { "type": "integer" },
                          "url": { "type": "string" },
                          "inventoryApi": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/segments": {
      "get": {
        "operationId": "listSegments",
        "summary": "List curated shopping categories (buyer intent + metro)",
        "description": "Prefer this when a buyer's request matches a category such as used trucks under $25,000 in Knoxville. Each item includes a human page and a JSON twin.",
        "responses": {
          "200": {
            "description": "Live shopping categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "computedAt": { "type": ["string", "null"] },
                    "segments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "label": { "type": "string" },
                          "market": {
                            "type": "object",
                            "properties": {
                              "city": { "type": "string" },
                              "state": { "type": "string" }
                            }
                          },
                          "vehicleCount": { "type": "integer" },
                          "page": { "type": "string" },
                          "json": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/lead": {
      "post": {
        "operationId": "submitInquiry",
        "summary": "Submit a buyer inquiry to a dealership",
        "description": "Sends the buyer's contact details and question to the selling dealership, which responds directly, usually within minutes. Agents must have the buyer's explicit consent to share their name and phone number and for the dealership to contact them.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["dealerId", "name", "phone"],
                "properties": {
                  "dealerId": { "type": "string", "description": "From vehicle.dealer.id or /api/v1/dealers" },
                  "vin": { "type": "string", "description": "Vehicle id from search results; omit for a general inquiry" },
                  "name": { "type": "string" },
                  "phone": { "type": "string" },
                  "email": { "type": "string" },
                  "message": { "type": "string" },
                  "source": { "type": "string", "description": "Where this inquiry originated, e.g. 'agent'", "default": "agent" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Inquiry delivered to the dealership" },
          "400": { "description": "Missing name or phone" },
          "404": { "description": "Unknown dealerId" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Vehicle": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Stable listing id; equals the VIN when known" },
          "name": { "type": "string" },
          "year": { "type": ["integer", "null"] },
          "make": { "type": ["string", "null"] },
          "model": { "type": ["string", "null"] },
          "trim": { "type": ["string", "null"] },
          "bodyStyle": { "type": ["string", "null"] },
          "color": { "type": ["string", "null"] },
          "condition": { "type": "string", "enum": ["new", "used"] },
          "price": { "type": ["integer", "null"], "description": "USD" },
          "mileage": { "type": ["integer", "null"] },
          "vin": { "type": ["string", "null"] },
          "image": { "type": ["string", "null"] },
          "url": { "type": "string", "description": "Human-facing vehicle page on carchat.io" },
          "dealer": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" },
              "city": { "type": ["string", "null"] },
              "state": { "type": ["string", "null"] },
              "url": { "type": "string" }
            }
          }
        }
      }
    }
  }
}