Use this endpoint 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`). Add `year`, `make`, and `model` filters to get better, more relevant results at each step.

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.

**Bulk variant list:** `dimension=variants` with `year` + `make` (no `model`) returns every variant for that make in one flat array.

---

## Billing

Most requests cost **1 unit**.

Exception: `dimension=variants` with `year` + `make` and no `model` costs **1 unit per model**. The response includes `modelCount`, the number of distinct models, which is also the amount billed — with a minimum of 1 unit even when zero models match.

Example: 82 variant strings across 12 models → `modelCount: 12` → **12 units**.

---

<Row>
  <Col>

    Retrieve distinct values for Year, Make, Model, or Variant lists, filtered by the parameters you supply.

    ---

    ## Required attributes

    <Properties>
      <Property name="key" type="string">
        Your CarsXE API key.
      </Property>
    </Properties>

    ## Optional attributes

    <Properties>
      <Property name="dimension" type="string">
        One of `years`, `makes`, `models`, `trims`, or `variants`. When set, the response contains exactly that one array if the required filters for that dimension are present. When omitted, the response layer is inferred from `year`, `make`, and `model` — see the table below.
      </Property>
      <Property name="year" type="string">
        Filter to a specific manufacturing year. Required when you filter by `model` without `make`.
      </Property>
      <Property name="make" type="string">
        Filter to a specific manufacturer (e.g., Toyota, Ford, Lexus). Required for `dimension=models`.
      </Property>
      <Property name="model" type="string">
        Filter to a specific model (e.g., Camry, F-150, LX). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set. Also required for inferred variants when `make` is omitted.
      </Property>
      <Property name="trim" type="string">
        Optional substring filter on trim names. Only applied when querying `dimension=trims` or `dimension=variants` (ignored for `years`, `makes`, and `models`).
      </Property>
    </Properties>

    ### Automatic response shape (no `dimension` given)

    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** — add `make` if the name appears under multiple makes (e.g. `Sentra`) |

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

    ### Explicit `dimension` values

    You can also set `dimension` directly. `trims` and `variants` share most filter rules; `variants` also accepts `year` + `make` (no `model`) for a bulk list. `variants` returns friendly display strings (`"Tacoma TRD Pro"`), while `trims` returns shorter manufacturer trim names.

    | `dimension` | Typical use | Required filters |
    | --- | --- | --- |
    | `years` | List years (optionally for a known make + model) | — |
    | `makes` | List makes (optionally for a known year) | — |
    | `models` | List models for a make | `make` |
    | `trims` | Shorter manufacturer trim names for a vehicle | `model` (+ `year` when `make` omitted; + `make` when model is ambiguous) |
    | `variants` | Model + trim display strings for menus | `year` + `make` for a bulk list, or `model` (+ `year` when `make` omitted; + `make` when model is ambiguous) |

    If you request `dimension=variants` or `dimension=trims` with only `make` (no `year`), the API returns `models` for that make with a `message` explaining that `model` is needed next — it does not error. With `dimension=variants`, `year`, and `make`, you get all variants for that make/year in one response.

    ---

    ## Response attributes

    <Properties>
      <Property name="success" type="boolean">
        Indicates whether the request was successful.
      </Property>
      <Property name="input" type="object">
        Echoes back only the query parameters you submitted.
      </Property>
      <Property name="message" type="string">
        Optional guidance when the returned layer differs from the requested `dimension`, or when explaining what to add next for better results.
      </Property>
      <Property name="years / makes / models" type="array">
        Distinct values for that layer when applicable.
      </Property>
      <Property name="variants" type="array of strings">
        Combined model + trim display strings, deduplicated.
      </Property>
      <Property name="trims" type="array of strings">
        Shorter manufacturer trim names — only when `dimension=trims` with sufficient filters.
      </Property>
      <Property name="modelCount" type="number">
        Present only for bulk variants (`dimension=variants` + year + make, no model). Equals the number of distinct models, which is also the amount billed — except a zero-match query, which returns `modelCount: 0` but still bills a minimum of 1 unit.
      </Property>
    </Properties>

    <FAQ faqs={[
      {
        question: "Why did I get models when I asked for variants?",
        answer: <>You requested <code>dimension=variants</code> (or <code>trims</code>) with only <code>make</code> and no <code>year</code>. The API returns <code>models</code> for that make and a <code>message</code> telling you to add <code>model=...</code> on the next call. With <code>dimension=variants</code>, <code>year</code>, and <code>make</code>, you get variants directly.</>
      },
      {
        question: "How is usage billed?",
        answer: <>Most requests cost 1 unit. Exception: <code>dimension=variants</code> with <code>year</code> + <code>make</code> and no <code>model</code> costs 1 unit per model. Check <code>modelCount</code> in the response — that is the amount billed, with a minimum of 1 unit.</>
      },
      {
        question: "Why do I need year or make when I only have a model name?",
        answer: <>Without <code>make</code>, a <code>year</code> filter is required. If that model name appears under multiple makes for that year (e.g. <code>Sentra</code>), add <code>make</code> as well. If the name is unique to one make, <code>year</code> + <code>model</code> is enough.</>
      },
      {
        question: "What is the difference between trims and variants?",
        answer: <><code>variants</code> returns display-ready strings like <code>"Tacoma TRD Pro"</code>. <code>trims</code> returns shorter manufacturer trim names. Both need a <code>model</code> (or disambiguating <code>year</code>/<code>make</code>) for single-vehicle lookups; only <code>dimension=variants</code> accepts <code>year</code> + <code>make</code> without <code>model</code> for a bulk list. For dropdown menus, use inferred responses or <code>dimension=variants</code>.</>
      },
      {
        question: "Does this endpoint require an API key?",
        answer: <>Yes — every request requires a valid, active CarsXE API key and counts toward your Year Make Model Options quota.</>
      }
    ]} hidePadding />

  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="GET" label="/v1/ymm-options">

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

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

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

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

    # Variants when you only know year + model (works when the name is unique to one make)
    curl -G https://api.carsxe.com/v1/ymm-options \
      -d key=CARSXE_API_KEY \
      -d year=2026 \
      -d model=Tacoma

    # All variants for a make+year in one call (billed per model — see modelCount)
    curl -G https://api.carsxe.com/v1/ymm-options \
      -d key=CARSXE_API_KEY \
      -d dimension=variants \
      -d year=2025 \
      -d make=Lexus

    # Explicit dimension=variants with make only (no year) — returns models + guidance message
    curl -G https://api.carsxe.com/v1/ymm-options \
      -d key=CARSXE_API_KEY \
      -d dimension=variants \
      -d make=Toyota

    # Reversed lookup — which years a make + model were sold
    curl -G https://api.carsxe.com/v1/ymm-options \
      -d key=CARSXE_API_KEY \
      -d dimension=years \
      -d make=Lexus \
      -d model=TX

    # Trim names for year + make + model (requires model — no bulk path for trims)
    curl -G https://api.carsxe.com/v1/ymm-options \
      -d key=CARSXE_API_KEY \
      -d dimension=trims \
      -d year=2026 \
      -d make=Toyota \
      -d model=Tacoma
    ```

    </CodeGroup>

    <CodeGroup title="Response" label="year=2026&make=Toyota&model=Tacoma">
    ```json showLineNumbers {{ title: 'Response' }}
    {
      "success": true,
      "input": { "year": 2026, "make": "Toyota", "model": "Tacoma" },
      "variants": [
        "Tacoma Limited",
        "Tacoma SR",
        "Tacoma SR5",
        "Tacoma TRD Off-Road",
        "Tacoma TRD PreRunner",
        "Tacoma TRD Pro",
        "Tacoma TRD Sport",
        "Tacoma Trailhunter"
      ]
    }
    ```
    </CodeGroup>

    <CodeGroup title="Response" label="make=Toyota (models only)">
    ```json showLineNumbers {{ title: 'Response' }}
    {
      "success": true,
      "input": { "make": "Toyota" },
      "models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"]
    }
    ```
    </CodeGroup>

    <CodeGroup title="Response" label="dimension=variants&year=2025&make=Lexus">
    ```json showLineNumbers {{ title: 'Response' }}
    {
      "success": true,
      "input": { "dimension": "variants", "year": 2025, "make": "Lexus" },
      "variants": [
        "ES 250",
        "ES 300h",
        "GX 550 Premium",
        "IS 300",
        "LC 500",
        "LS 500",
        "LX 600 Premium",
        "NX 350",
        "RC 350",
        "RX 350",
        "RZ 450e",
        "TX 350",
        "UX 300h"
      ],
      "modelCount": 12
    }
    ```
    </CodeGroup>

    <CodeGroup title="Response" label="dimension=variants&make=Toyota (no year — fallback)">
    ```json showLineNumbers {{ title: 'Response' }}
    {
      "success": true,
      "input": { "dimension": "variants", "make": "Toyota" },
      "message": "To receive variants, include a model filter with this make. Models are returned instead.",
      "models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"]
    }
    ```
    </CodeGroup>

  </Col>
</Row>