---
title: "Spec sheet at the model-year (or trim) grain"
method: GET
path: "/v2/specs/{ref}"
tags: ["specs"]
---

# Spec sheet at the model-year (or trim) grain

`GET /v2/specs/{ref}`

## Request

- Base URL: `https://api.cardog.app`
- URL: `https://api.cardog.app/v2/specs/{ref}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

`refs` is the identity card (the same keys as `GET /v2/vin/{vin}`). Values are grouped by catalog section, each `{ value, unit?, stated? }`: every number is metric (horsepower and inch sizes excepted) and states its unit; `stated` is the source's own number when it published another unit. The root is the overlap of everything under the model year: a decode field (`refs`, engine columns) is served only when every decoded build states the same value, and a catalogue value only when every trim behind the sheet states it; ask for the trim grain with `?trim=`, or the build grain. `markets.US` and `markets.CA` hold what each market publishes: `pricing.msrp` (every price by trim and style, cheapest first, in the market's `currency`) and `colors` (name, rgb, hex). Markets are never merged.

## Path parameters

- `ref` string, required

## Query parameters

- `trim` string

## Response `200`

The sheet: sections, markets

- SpecSheet
  - `ref` string, required: The requested model-year ref
  - `grain` 'model-year' | 'trim', required
  - `trim` string, nullable: Set when grain=trim
  - `year` integer, nullable, required
  - `make` string, nullable, required: Display name
  - `model` string, nullable, required: Display name
  - `refs` object, required: The identity card's refs, the same keys as `GET /v2/vin/{vin}`: the join keys. An attribute served here is not repeated in `sections`
    - `make` string, nullable, required: Make entity ref, e.g. "make:tesla"
    - `model` string, nullable, required: Model entity ref, e.g. "model:tesla/model-y"
    - `modelYear` string, required: The model-year ref, always set on a sheet, e.g. "model-year:toyota/rav4/2021"; `links.modelYearSheet` is its sheet
    - `bodyStyle` string, nullable, required
    - `fuelType` string, nullable, required
    - `driveType` string, nullable, required
    - `transmission` string, nullable, required
    - `electrificationLevel` string, nullable, required
    - `vehicleType` string, nullable, required
    - `gvwr` string, nullable
    - `country` string, nullable, required: Ref of the country the vehicle was built in, e.g. "country:canada"
    - `bodyCab` string, nullable
    - `bedType` string, nullable
    - `series` string, nullable
    - `fuelTypeSecondary` string, nullable
    - `trailerBodyType` string, nullable
    - `trailerType` string, nullable
  - `sections` object, required
  - `markets` object, required: Per-market pricing and colors; a market with nothing published is absent
    - `US` object
      - `currency` 'USD' | 'CAD', required
      - `pricing` object
        - `msrp` object[], required: Every published price, cheapest first
          - `trim` string, nullable, required: The trim the price is for; null when the publisher names none
          - `style` string, nullable, required: The publisher's style name, for display; two prices of one trim differ by it
          - `msrp` number, required: Whole units of the market's `currency`
          - `source` 'catalogue' | 'sticker' | 'oem', required
      - `colors` object: Every color offered in this market across the trims behind the sheet, sorted by name
        - `colorsExterior` object[]
          - `name` string, required
          - `rgb` integer[], nullable, required: 0–255 each; null when not published
          - `hex` string, nullable, required: "#rrggbb", from `rgb`; null when not published
        - `colorsInterior` object[]
          - `name` string, required
          - `rgb` integer[], nullable, required: 0–255 each; null when not published
          - `hex` string, nullable, required: "#rrggbb", from `rgb`; null when not published
    - `CA` object
      - `currency` 'USD' | 'CAD', required
      - `pricing` object
        - `msrp` object[], required: Every published price, cheapest first
          - `trim` string, nullable, required: The trim the price is for; null when the publisher names none
          - `style` string, nullable, required: The publisher's style name, for display; two prices of one trim differ by it
          - `msrp` number, required: Whole units of the market's `currency`
          - `source` 'catalogue' | 'sticker' | 'oem', required
      - `colors` object: Every color offered in this market across the trims behind the sheet, sorted by name
        - `colorsExterior` object[]
          - `name` string, required
          - `rgb` integer[], nullable, required: 0–255 each; null when not published
          - `hex` string, nullable, required: "#rrggbb", from `rgb`; null when not published
        - `colorsInterior` object[]
          - `name` string, required
          - `rgb` integer[], nullable, required: 0–255 each; null when not published
          - `hex` string, nullable, required: "#rrggbb", from `rgb`; null when not published
  - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

## Other responses

- `400`: Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
- `401`: No valid credential (API key, session, or internal token)
- `404`: Resource not found
- `429`: Per-minute rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/cardog/apis/cardog-api-v2.md) · [All operations](https://skmtc.dev/cardog/apis/cardog-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/cardog/apis/cardog-api-v2/revisions/b9d48193126f?raw)