Vehicles & search

List years, makes and models; search and resolve free text.

Images are bounded to the open-source @meterapp/vehicle-db catalog. These free endpoints let you discover valid years, makes and models, search them, and turn a human phrase into exact image parameters — so you never guess and never see a 404.

List years, makes and models

GET/api/v1/vehicles

images:readfree

Parameter	Type	Description
`year`	integer	Restrict makes (and models) to those sold in this model year.
`makeId`	integer	With year: list models for this make. IDs come from the makes response.
`q`	string	Free-text search across makes and models (see below). Combine with year to filter.

The response shape follows the parameters you pass:

bash

# Years available in the catalog
curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" "https://carimage.dev/api/v1/vehicles"
# → { "data": { "years": [2026, 2025, …, 1990] }, "request_id": "…" }

# Makes sold in 2024
curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" "https://carimage.dev/api/v1/vehicles?year=2024"
# → { "data": { "makes": [{ "makeId": 449, "makeName": "Porsche", "slug": "porsche" }, …] } }

# Models for a make in 2024
curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" "https://carimage.dev/api/v1/vehicles?year=2024&makeId=449"
# → { "data": { "models": [{ "name": "911", "slug": "911", "vehicleType": "Passenger Car" }, …] } }

Slugs are what the image endpoint wants

Use the slug values as make and model. Display names are normalized the same way on the server, so either works — slugs are just unambiguous.

Search

?q= searches makes and models with deterministic ranking: exact, prefix, token, substring, then conservative typo matching. Duplicate catalog rows are merged, and within a match kind the models with the longest production history rank first. A year inside the query is detected automatically.

bash

curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  "https://carimage.dev/api/v1/vehicles?q=mustang&year=2024"

200 OK

{
  "data": {
    "results": [
      {
        "kind": "model",
        "makeId": 460,
        "makeName": "Ford",
        "makeSlug": "ford",
        "modelName": "Mustang",
        "modelSlug": "mustang",
        "vehicleType": "Passenger Car",
        "years": [
          2024
        ],
        "matchKind": "exact"
      },
      {
        "kind": "model",
        "makeId": 460,
        "makeName": "Ford",
        "makeSlug": "ford",
        "modelName": "Mustang Mach-E",
        "modelSlug": "mustang-mach-e",
        "vehicleType": "Passenger Car",
        "years": [
          2024
        ],
        "matchKind": "prefix"
      }
    ]
  },
  "request_id": "req_01j9x…"
}

Resolve free text

POST/api/v1/images/resolve

images:readfree

Give it a phrase the way a person (or an LLM) would say it and get back exact request parameters. Colors like "navy" or "charcoal" map onto the presets, angles like "hero shot" or "from behind" map onto views, and the rest goes to catalog search. The resolver is rule-based and deterministic: the same phrase always resolves the same way.

Parameter	Type	Description
`query`required	string	The phrase to resolve, e.g. "red 2024 porsche 911 side profile".
`year`	integer	Fallback model year when the phrase has none.

bash

curl -X POST https://carimage.dev/api/v1/images/resolve \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "navy 2022 bmw m3 hero shot, webp"}'

200 OK

{
  "data": {
    "resolved": true,
    "confidence": "high",
    "params": {
      "make": "bmw",
      "model": "m3",
      "year": 2022,
      "view": "front-3-4",
      "color": "blue",
      "format": "webp"
    },
    "image_path": "/api/v1/images/car?make=bmw&model=m3&year=2022&view=front-3-4&color=blue&format=webp",
    "candidates": [
      {
        "make": "bmw",
        "model": "m3",
        "years": [
          2022
        ],
        "matchKind": "exact"
      },
      {
        "make": "bmw",
        "model": "m3-competition",
        "years": [
          2022
        ],
        "matchKind": "prefix"
      }
    ]
  },
  "request_id": "req_01j9x…"
}

When the phrase is ambiguous, resolved is false, confidence is low and candidates lists the options to show a user. Agents get the same behavior through the resolve_vehicle tool.

A vehicle is missing

The catalog is open source. If a make, model or model year is absent, add it to vehicle-db — the API picks up new releases, and every customer benefits.