CarsXECarsXE

Use /v1/ymm-options to power cascading dropdowns in your own UI. Each request returns exactly one list — years, makes, models, variants (combined model + trim display strings, e.g. "Tacoma TRD Pro"), or trims (shorter manufacturer trim names when you explicitly request dimension=trims).

Typical flow: start with no filters to list years → add year for makes → add make for models → add model for variants. One API call per dropdown level.

Need full vehicle specs for a selected year, make, and model? Use Year Make Model (/v1/ymm) instead.

Endpoint: /v1/ymm-options

Parameters

ParameterRequiredDescription
keyYesYour CarsXE API key
dimensionNoOne of years, makes, models, trims, or variants. When set, the response contains exactly that array when the required filters are present. When omitted, the response layer is inferred from year, make, and model.
yearNoFilter to a specific manufacturing year. Required when filtering by model without make.
makeNoFilter to a manufacturer (e.g. Toyota, Ford, Lexus). Required for dimension=models.
modelNoFilter to a model (e.g. Camry, F-150, LX). Required for dimension=trims and for dimension=variants unless both year and make are set (bulk variant list).

Automatic response shape (no dimension)

Omit dimension and the API returns one array inferred from your filters:

make?model?year?Returns
———years
——✓makes
✓—*models
✓✓*variants
—✓—400 — year required when model is given without make
—✓✓variants if that model name maps to one make that year; 400 if ambiguous (add make)

The API never returns more than one layer per response. To populate both a model list and a variant list, make two calls.

Bulk variant list

Set dimension=variants with year + make (no model) to fetch every variant for that make in one flat array — useful for client-side search or filter UIs. This path bills one lookup unit per distinct model in the result (e.g. 82 Lexus variant strings across 12 models = 12 billed units).

Example

Populate a cascading dropdown

Code
# Step 1 — list years (no filters)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY

# Step 2 — makes for a year
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026

# Step 3 — models for a make
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d make=Toyota

# Step 4 — variants for year + make + model
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026 \
  -d make=Toyota \
  -d model=Tacoma

# Bulk variants for a make + year (bills per distinct model)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d dimension=variants \
  -d year=2025 \
  -d make=Lexus

Response

Top-level shape

{
"success": true,// always true on 200
"message": "optional guidance when the returned layer differs",// optional
}

Click input or a returned array to expand sample values. For the full interactive reference, try it live in the API Reference.

Each successful response includes success: true and exactly one of years, makes, models, trims, or variants. The message field is optional guidance when the returned layer differs from what you requested.

variants vs trims

variants returns display-ready strings like "Tacoma TRD Pro". trims returns shorter manufacturer trim names. Both need a model (or disambiguating year/make) for single-vehicle lookups; only dimension=variants accepts year + make without model for a bulk list. For dropdown menus, use inferred responses or dimension=variants.

Every request requires a valid, active CarsXE API key and counts toward your Year Make Model Options quota — a separate bucket from Year Make Model.

Errors

StatusWhen it happens
400Invalid dimension, missing required filters, or ambiguous model without make
401Missing or invalid API key
429Usage limit exceeded
500Could not fetch data

See the Errors guide for general error handling guidance.