## Reference: Parts

OEM part numbers by model year, linked to the manufacturer's official parts store

**Availability: live** on `https://api.cardog.app`.

### GET /v2/parts/{ref}

OEM part numbers for a model year or build code, with where to buy them *Since 2026-10-26.*

The manufacturer part numbers on record for a model year, each with the document that names it and, where known, a link to that number on the manufacturer's official parts store. The root `acquire` lists the official stores for the make by market. Parts apply at the model-year grain: a part listed applies to some builds of the model year, not necessarily every vehicle. A `nano:` ref is answered at its model year. Today's source is the part numbers manufacturers file with NHTSA recalls, so `coverage.complete` is false: this is not the full catalogue. No prices; the store has the current one.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ref` | string | yes | A model-year: or nano: ref. Slashes in refs must be URL-encoded (%2F). |

**Response 200** `Parts`: Parts with sources, links to the official store, and the stores for the make

- `ref` (string): The queried ref
- `grain` ("model-year"): The grain the parts apply at. "model-year": each part applies to some builds of the model year, not necessarily every vehicle. A nano request is answered at this grain.
- `modelYearRef` (string): Entity ref ({domain}:{key}) in the "model-year" domain. Example: "model-year:toyota/rav4/2021"
- `total` (integer)
- `parts` (object[])
  - `parts[].ref` (string): Entity ref ({domain}:{key}) in the "part" domain. Example: "part:hyundai/4295118110"
  - `parts[].partNumber` (string): The number as the manufacturer printed it, e.g. "42951-18110"
  - `parts[].make` (string): The make the part is sold under
  - `parts[].name` (string | null): The manufacturer's name for the part
  - `parts[].description` (string | null)
  - `parts[].component` (object | null): The component the part belongs to. A `ref` into the shared component tree joins this object when the tree ships (additive).
    - `parts[].component.asPublished` (string): The system it belongs to, verbatim as the authority files it, e.g. "PARKING BRAKE:ELECTRICAL:CONTROL MODULE:SOFTWARE". The same field name recall rows use for the same text.
  - `parts[].sources` (object[])
    - `parts[].sources[].source` (string): Who published it, as an ocean source id, e.g. "gov:nhtsa"
    - `parts[].sources[].ref` (string): The document that names the part (today: the recall campaign it was filed with)
    - `parts[].sources[].observedAt` (string | null): When that document was published (ISO date); null if undated
  - `parts[].recalls` (string[]): The recall campaigns that name this part for this model year: the distinct recall refs among `sources`.
  - `parts[].acquire`? (object[]): This number on the manufacturer's official store, where a link to it is known. Absent otherwise; use the root `acquire` stores.
    - `parts[].acquire[].market` ("CA" | "US"): Market the store sells into
    - `parts[].acquire[].kind` ("search" | "product"): "search" opens the store's search for this number; "product" opens the part's own page
    - `parts[].acquire[].url` (string (uri))
- `acquire` (object[]): The manufacturer's official parts stores for this make, by market. Empty when none is on file.
  - `acquire[].make` (string): Entity ref ({domain}:{key}) in the "make" domain. Example: "make:toyota"
  - `acquire[].market` ("CA" | "US"): Market the store sells into
  - `acquire[].name` (string): The store's own name, e.g. "Hyundai Canada Parts"
  - `acquire[].url` (string (uri)): The store's home page (absolute URL on the manufacturer's site)
- `coverage` (object)
  - `coverage.complete` (false): Always false today: the list is the part numbers named on the public record, not the full catalogue for the vehicle
  - `coverage.sources` (string[]): Sources the list is built from, e.g. ["gov:nhtsa"]
  - `coverage.unpaired` (integer): Part numbers a document names for several vehicles at once without saying which is this one's (a multi-vehicle recall filed as a cross product). Not in `parts`: listing them would claim a fit the record does not make.
- `links`? (object): Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 404, 429, 500

**Example: cURL**

```bash
curl "https://api.cardog.app/v2/parts/model-year:hyundai%2Fioniq-5%2F2022" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const parts = await client.v2.parts.byRef("model-year:hyundai/ioniq-5/2022");
console.log(parts.ref);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

parts = client.v2.parts.by_ref("model-year:hyundai/ioniq-5/2022")
print(parts.ref)
```

---

Previous: [Specs](https://cardog.app/docs/reference/specs.md) (API reference)
Next: [Feeds](https://cardog.app/docs/reference/feeds.md) (API reference)