How do I map my vehicle list to the catalog?

Do not guess slugs. Send your whole list once to check_vehicles (POST /api/v1/vehicles/check, or car-image check for a file): every entry comes back as a match with its vehicle id, a suggestion, a miss or an invalid line, read by the same rules the image endpoints use. Store the id (veh_ followed by 13 characters) and render with vehicle=<id>; ids never change. For one car at a time, resolve_vehicle reads a free-text year, make and model and search_vehicles browses; a VIN decodes for free.

The catalog is make, model and model year: a facelift, chassis code, trim or special edition is not its own entry unless it is sold as a distinct model, and a body style, performance derivative or EV twin is never substituted. A miss is a real gap: show your own placeholder rather than a wrong car, and request the vehicle so you are emailed when it lands. Renders are studio illustrations and can miss a detail; rate a bad one from the dashboard and it is re-rendered.