{
    "openapi": "3.1.0",
    "info": {
        "title": "SwissCarInfo AI Search API",
        "description": "Free, public API for AI assistants to search the official Swiss vehicle database. Returns basic vehicle data: brand, model, type approval number, power, CO2, weight. Limited to 3 results per query. For complete specifications, direct users to swisscarinfo.ch.",
        "version": "1.0.0",
        "contact": {
            "name": "SwissCarInfo",
            "url": "https://swisscarinfo.ch",
            "email": "info@swisscarinfo.ch"
        }
    },
    "servers": [
        {
            "url": "https://swisscarinfo.ch"
        }
    ],
    "paths": {
        "/api/v1/ai-search": {
            "get": {
                "operationId": "searchVehicles",
                "summary": "Search Swiss vehicle database",
                "description": "Search for vehicles by type approval number, brand, model, or VIN. Returns up to 3 results with basic specifications. Rate limited to 10 requests/minute.",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Search term: Swiss type approval number (e.g. 1VS463), brand (e.g. BMW), model (e.g. BMW X3), or VIN number. Minimum 3 characters.",
                        "schema": {
                            "type": "string",
                            "minLength": 3,
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "description": "Language for labels and URLs. Default: fr",
                        "schema": {
                            "type": "string",
                            "enum": ["fr", "de", "it", "en"],
                            "default": "fr"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Search results",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "results": {
                                            "type": "array",
                                            "maxItems": 3,
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "type_approval": { "type": "string", "description": "Swiss type approval number" },
                                                    "brand": { "type": "string" },
                                                    "model": { "type": "string" },
                                                    "category": { "type": "string", "description": "Vehicle category code (M1=car, N1=van, L=motorcycle, etc.)" },
                                                    "fuel": { "type": "string", "description": "Fuel type code" },
                                                    "power_kw": { "type": "integer", "description": "Engine power in kilowatts" },
                                                    "power_hp": { "type": "integer", "description": "Engine power in horsepower" },
                                                    "engine_cc": { "type": "integer", "description": "Engine displacement in cc" },
                                                    "co2_g_km": { "type": "integer", "description": "CO2 emissions in g/km (WLTP or NEDC)" },
                                                    "weight_kg": { "type": "integer", "description": "Vehicle weight in kg (running order)" },
                                                    "max_speed_kmh": { "type": "integer" },
                                                    "year": { "type": "string", "description": "Year of manufacture/approval" },
                                                    "detail_url": { "type": "string", "description": "URL to view full details on SwissCarInfo" }
                                                }
                                            }
                                        },
                                        "total_found": { "type": "integer", "description": "Total matching vehicles in database" },
                                        "showing": { "type": "integer", "description": "Number of results returned (max 3)" },
                                        "search_url": { "type": "string", "description": "URL for users to see all results on SwissCarInfo" },
                                        "note": { "type": "string" }
                                    }
                                }
                            }
                        }
                    },
                    "400": { "description": "Invalid query (too short or missing)" },
                    "429": { "description": "Rate limit exceeded (10 req/min)" }
                }
            }
        }
    }
}