{
  "openapi": "3.1.0",
  "info": {
    "title": "RidePrise Car Search API",
    "version": "1.0.0",
    "description": "Public, read-only API for searching available rental cars across Albania on the RidePrise marketplace. Returns verified-partner vehicles with transparent, computed daily pricing in EUR. No authentication required.",
    "contact": { "name": "RidePrise", "email": "info@rideprise.com", "url": "https://rideprise.com" },
    "license": { "name": "Proprietary" }
  },
  "servers": [{ "url": "https://rideprise.com", "description": "Production" }],
  "paths": {
    "/api/cars": {
      "get": {
        "operationId": "searchCars",
        "summary": "Search available rental cars in Albania",
        "description": "Returns the list of active, approved rental cars, optionally filtered by city, category and maximum daily price. Pickup/return dates are accepted but currently informational (not used for availability filtering).",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "City / pickup location filter (e.g. 'Tirana', 'Saranda').",
            "schema": { "type": "string" }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Vehicle category.",
            "schema": { "type": "string", "enum": ["economy", "standard", "suv", "premium"] }
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "description": "Maximum price per day in EUR.",
            "schema": { "type": "number", "minimum": 0 }
          },
          {
            "name": "pickup",
            "in": "query",
            "required": false,
            "description": "Pickup date (YYYY-MM-DD). Informational only.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "description": "Return date (YYYY-MM-DD). Informational only.",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching cars, ordered by price ascending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "integer", "description": "Number of cars returned." },
                    "filters_applied": { "type": "object", "description": "Echo of the filters that were applied." },
                    "search_url": { "type": "string", "format": "uri", "description": "Human-facing search results URL on rideprise.com." },
                    "cars": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Car" }
                    }
                  },
                  "required": ["results", "cars"]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Car": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "description": "Make Model Year, e.g. 'Opel Astra 2008'." },
          "make": { "type": "string" },
          "model": { "type": "string" },
          "year": { "type": "integer" },
          "category": { "type": "string", "enum": ["economy", "standard", "suv", "premium"] },
          "seats": { "type": "integer" },
          "transmission": { "type": "string", "enum": ["manual", "automatic"] },
          "fuel_type": { "type": "string" },
          "air_conditioning": { "type": "boolean" },
          "price_per_day_eur": { "type": "number", "description": "Final daily price shown to the customer, in EUR." }
        }
      }
    }
  }
}