Listings

live

Ref-native listing search, counts, facets

GET/v2/listings/search

Search listings — ref filters + spec filters

Filters are entity refs, checked for grammar and then registry membership — an unknown ref returns a 400 naming it, never a silent fuzzy match. Sort: `?sort=<field>&order=<asc|desc>`.

Query parameters

ParameterType
curl "https://api.cardog.app/v2/listings/search?make=make:tesla&year.min=2022&limit=5" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingSearch

FieldType

Example response

4 keys
"response": {
"listings": [
0: {60 items},
1: {60 items},
2: {60 items},
3: {60 items},
4: {60 items}
],
"pagination": {
"page": 1,
"limit": 5
},
"sort": {
"field": "price",
"order": "asc"
},
"filters": {
"makes": [2 items],
"year": {1 item}
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/listings/count

Count matching listings (distinct VINs)

Query parameters

ParameterType
curl "https://api.cardog.app/v2/listings/count?make=make:tesla" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingCount

FieldType

Example response

3 keys
"response": {
"count": 294,
"countIsApproximate": false,
"filters": {
"makes": [1 item],
"price": {1 item}
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/listings/facets

Facets over the filtered set — (ref, name, count) buckets

Query parameters

ParameterType
curl "https://api.cardog.app/v2/listings/facets?make=make:tesla" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingFacets

FieldType

Example response

19 keys
"response": {
"makes": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items},
16: {3 items},
17: {3 items},
18: {3 items},
19: {3 items},
20: {3 items},
21: {3 items},
22: {3 items},
23: {3 items},
24: {3 items},
25: {3 items},
26: {3 items},
27: {3 items},
28: {3 items},
29: {3 items},
30: {3 items},
31: {3 items},
32: {3 items},
33: {3 items},
34: {3 items},
35: {3 items},
36: {3 items},
37: {3 items},
38: {3 items},
39: {3 items}
],
"models": [
0: {4 items},
1: {4 items},
2: {4 items},
3: {4 items},
4: {4 items},
5: {4 items},
6: {4 items},
7: {4 items},
8: {4 items},
9: {4 items},
10: {4 items},
11: {4 items},
12: {4 items},
13: {4 items},
14: {4 items},
15: {4 items},
16: {4 items},
17: {4 items},
18: {4 items},
19: {4 items},
20: {4 items},
21: {4 items},
22: {4 items},
23: {4 items},
24: {4 items},
25: {4 items},
26: {4 items},
27: {4 items},
28: {4 items},
29: {4 items},
30: {4 items},
31: {4 items},
32: {4 items},
33: {4 items},
34: {4 items},
35: {4 items},
36: {4 items},
37: {4 items},
38: {4 items},
39: {4 items},
40: {4 items},
41: {4 items},
42: {4 items},
43: {4 items},
44: {4 items},
45: {4 items},
46: {4 items},
47: {4 items},
48: {4 items},
49: {4 items},
50: {4 items},
51: {4 items},
52: {4 items},
53: {4 items},
54: {4 items},
55: {4 items},
56: {4 items},
57: {4 items},
58: {4 items},
59: {4 items},
60: {4 items},
61: {4 items},
62: {4 items},
63: {4 items},
64: {4 items},
65: {4 items},
66: {4 items},
67: {4 items},
68: {4 items},
69: {4 items},
70: {4 items},
71: {4 items},
72: {4 items},
73: {4 items},
74: {4 items},
75: {4 items},
76: {4 items},
77: {4 items},
78: {4 items},
79: {4 items},
80: {4 items},
81: {4 items},
82: {4 items},
83: {4 items},
84: {4 items},
85: {4 items},
86: {4 items},
87: {4 items},
88: {4 items},
89: {4 items},
90: {4 items},
91: {4 items},
92: {4 items},
93: {4 items},
94: {4 items},
95: {4 items},
96: {4 items},
97: {4 items},
98: {4 items},
99: {4 items},
100: {4 items},
101: {4 items},
102: {4 items},
103: {4 items},
104: {4 items},
105: {4 items},
106: {4 items},
107: {4 items},
108: {4 items},
109: {4 items},
110: {4 items},
111: {4 items},
112: {4 items},
113: {4 items},
114: {4 items},
115: {4 items},
116: {4 items},
117: {4 items},
118: {4 items},
119: {4 items},
120: {4 items},
121: {4 items},
122: {4 items},
123: {4 items},
124: {4 items},
125: {4 items},
126: {4 items},
127: {4 items},
128: {4 items},
129: {4 items},
130: {4 items},
131: {4 items},
132: {4 items},
133: {4 items},
134: {4 items},
135: {4 items},
136: {4 items},
137: {4 items},
138: {4 items},
139: {4 items},
140: {4 items},
141: {4 items},
142: {4 items},
143: {4 items},
144: {4 items},
145: {4 items}
],
"bodyStyles": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items}
],
"fuelTypes": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items}
],
"driveTypes": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items}
],
"transmissions": [
0: {3 items},
1: {3 items}
],
"electrificationLevels": [
0: {3 items},
1: {3 items}
],
"vehicleTypes": [
0: {3 items},
1: {3 items}
],
"exteriorColors": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items}
],
"saleTypes": [
0: {3 items},
1: {3 items}
],
"years": {
"min": 2022,
"max": 2027
},
"prices": {
"min": 5001,
"max": 998890
},
"odometer": {
"min": 1,
"max": 352289
},
"priceHistogram": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items},
16: {3 items},
17: {3 items},
18: {3 items},
19: {3 items}
],
"featureFacets": [
0: {4 items},
1: {4 items},
2: {4 items},
3: {4 items},
4: {4 items},
5: {4 items},
6: {4 items},
7: {4 items},
8: {4 items},
9: {4 items},
10: {4 items},
11: {4 items},
12: {4 items},
13: {4 items},
14: {4 items},
15: {4 items},
16: {4 items},
17: {4 items}
],
"specRanges": {
"range": {2 items},
"fuelEconomyCombined": {2 items},
"horsepowerFrom": {2 items},
"torque": {2 items},
"seatingCapacity": {2 items}
},
"featureFacetsAreApproximate": false,
"totalCount": 13599,
"totalCountIsApproximate": false
}

Errors — every non-2xx body is the error envelope: 400, 401, 402, 429, 500

GET/v2/listings/id/{id}

One listing by id

Path parameters

ParameterType
curl "https://api.cardog.app/v2/listings/id/$LISTING_ID" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingDetail

FieldType

Example response

63 keys
"response": {
"id": "87dc1b59-771d-475b-a6b7-37dd96df2516",
"vin": "5NPE34AFXHH588415",
"price": 14888,
"currency": "CAD",
"odometer": 94743,
"year": 2017,
"make": "Hyundai",
"model": "Sonata",
"trim": "Sport Tech",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"nano": null,
"media": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items},
16: {3 items},
17: {3 items},
18: {3 items},
19: {3 items}
],
"variant": null,
"spec": null,
"sellerId": "d98113ad-d5a7-4256-86ac-197c2842560c",
"websiteDomain": "motoauto.ca",
"sourceUri": "https://www.motoauto.ca/inventory/2017-hyundai-sonata-sport-tech/272/",
"stockNumber": "588415",
"score": 76,
"status": "active",
"mediaCount": 22,
"latitude": "53.57040000",
"longitude": "-113.47100000",
"location": {
"id": 35053,
"street": "8419 118 Ave NW",
"city": "Edmonton",
"state": "AB",
"postalCode": "T5B 0S6",
"country": "CA",
"latitude": "53.5704",
"longitude": "-113.471",
"location": {2 items},
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"createdAt": "2026-07-31T04:05:47.869Z",
"updatedAt": "2026-07-31T08:08:35.925Z",
"removedAt": null,
"previousPrice": null,
"priceChangedAt": null,
"verificationStatus": "verified",
"verificationReasons": [
],
"verifiedAt": "2026-07-31T08:08:35.925Z",
"lastSeenAt": "2026-07-31T08:08:35.925Z",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"seller": {
"id": "d98113ad-d5a7-4256-86ac-197c2842560c",
"type": "dealership",
"name": "Moto Auto",
"slug": "moto_auto",
"email": null,
"phone": null,
"addressId": 35053,
"dealershipId": "7efa15de-853a-41e3-a423-44529dc7c568",
"gmbPhone": "+17802442222",
"gmbRating": "4.7",
"gmbReviewCount": 286,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2026-01-28T20:53:42.879Z",
"deactivatedAt": null
},
"dealership": {
"id": "7efa15de-853a-41e3-a423-44529dc7c568",
"name": "Moto Auto",
"primaryDomain": "motoauto.ca",
"metadata": {3 items},
"isVerified": true,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"vehicle": {
"vin": "5NPE34AFXHH588415",
"make": "Hyundai",
"model": "Sonata",
"year": 2017,
"trim": "Sport Tech",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"nano": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"createdAt": "2026-07-31T04:05:47.160Z",
"updatedAt": "2026-07-31T04:05:47.160Z"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 404, 429, 500

GET/v2/listings/vin/{vin}

Listing detail by VIN — listing + variant + full canonical spec, one query

Path parameters

ParameterType
curl "https://api.cardog.app/v2/listings/vin/1HGCM82633A123456" \
  -H "x-api-key: $CARDOG_API_KEY"

Response 200 — ListingDetail

FieldType

Example response

63 keys
"response": {
"id": "87dc1b59-771d-475b-a6b7-37dd96df2516",
"vin": "5NPE34AFXHH588415",
"price": 14888,
"currency": "CAD",
"odometer": 94743,
"year": 2017,
"make": "Hyundai",
"model": "Sonata",
"trim": "Sport Tech",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"nano": null,
"media": [
0: {3 items},
1: {3 items},
2: {3 items},
3: {3 items},
4: {3 items},
5: {3 items},
6: {3 items},
7: {3 items},
8: {3 items},
9: {3 items},
10: {3 items},
11: {3 items},
12: {3 items},
13: {3 items},
14: {3 items},
15: {3 items},
16: {3 items},
17: {3 items},
18: {3 items},
19: {3 items}
],
"variant": null,
"spec": null,
"sellerId": "d98113ad-d5a7-4256-86ac-197c2842560c",
"websiteDomain": "motoauto.ca",
"sourceUri": "https://www.motoauto.ca/inventory/2017-hyundai-sonata-sport-tech/272/",
"stockNumber": "588415",
"score": 76,
"status": "active",
"mediaCount": 22,
"latitude": "53.57040000",
"longitude": "-113.47100000",
"location": {
"id": 35053,
"street": "8419 118 Ave NW",
"city": "Edmonton",
"state": "AB",
"postalCode": "T5B 0S6",
"country": "CA",
"latitude": "53.5704",
"longitude": "-113.471",
"location": {2 items},
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"createdAt": "2026-07-31T04:05:47.869Z",
"updatedAt": "2026-07-31T08:08:35.925Z",
"removedAt": null,
"previousPrice": null,
"priceChangedAt": null,
"verificationStatus": "verified",
"verificationReasons": [
],
"verifiedAt": "2026-07-31T08:08:35.925Z",
"lastSeenAt": "2026-07-31T08:08:35.925Z",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"seller": {
"id": "d98113ad-d5a7-4256-86ac-197c2842560c",
"type": "dealership",
"name": "Moto Auto",
"slug": "moto_auto",
"email": null,
"phone": null,
"addressId": 35053,
"dealershipId": "7efa15de-853a-41e3-a423-44529dc7c568",
"gmbPhone": "+17802442222",
"gmbRating": "4.7",
"gmbReviewCount": 286,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2026-01-28T20:53:42.879Z",
"deactivatedAt": null
},
"dealership": {
"id": "7efa15de-853a-41e3-a423-44529dc7c568",
"name": "Moto Auto",
"primaryDomain": "motoauto.ca",
"metadata": {3 items},
"isVerified": true,
"createdAt": "2025-02-09T07:43:40.075Z",
"updatedAt": "2025-02-09T07:43:40.075Z"
},
"vehicle": {
"vin": "5NPE34AFXHH588415",
"make": "Hyundai",
"model": "Sonata",
"year": 2017,
"trim": "Sport Tech",
"bodyStyle": "sedan",
"fuelType": "gasoline",
"driveTrain": null,
"transmission": null,
"engineSize": null,
"horsepower": null,
"torque": null,
"exteriorColor": "Black",
"interiorColor": "Black",
"condition": "used",
"makeRef": "make:hyundai",
"modelRef": "model:hyundai/sonata",
"makeRaw": null,
"bodyStyleRef": "body-style:sedan-saloon",
"fuelTypeRef": "fuel-type:gasoline",
"driveTypeRef": null,
"transmissionRef": null,
"vehicleTypeRef": null,
"electrificationLevelRef": null,
"gvwrRef": null,
"nano": null,
"cylinders": 4,
"displacement": "2.4",
"numberOfDoors": 4,
"shippingWeight": 3311,
"grossWeight": null,
"electrificationLevel": null,
"gvwr": null,
"vehicleType": "Passenger Car",
"createdAt": "2026-07-31T04:05:47.160Z",
"updatedAt": "2026-07-31T04:05:47.160Z"
}
}

Errors — every non-2xx body is the error envelope: 400, 401, 404, 429, 500

Generated from the contract. Machine-readable spec: GET https://api.cardog.app/v2/openapi.json · markdown twin: /docs/reference/listings.md