CL CarListAPI v1.x

CarListAPI Documentation

v1.x API docs for Automotive + Powersports. Includes auth, quick examples, responses, rate limits, caching, and demo endpoints.

Copy/paste quick start

Base URL + auth header for every request.

Introduction

CarListAPI provides normalized automotive and powersports data: year, make, model, trim, engines, and full details.

What you’ll need
  • An API token from your CarListAPI dashboard
  • The public IP address of the server making requests (must be added to the token’s allowlist)
  • URL-encode values with spaces (make/model/trim/engine)

Get started

CarListAPI is optimized for fast pickers: year → make → model → trim → details. Automotive includes engines; powersports may include sub-models and types.

1) Create an API token

Generate a token in your dashboard. If IP restrictions are enabled, requests must come from an allowed IP.

2) Base URL

All v1 endpoints:

Base URL 
https://carlistapi.com/api/v1
3) Authorization header

Send your token on every request:

Header 
Authorization: Bearer YOUR_API_TOKEN
4) Recommended flow

Automotive: years → makes → models → trims → engines → vehicle id → details
Powersports: years → makes → models → sub-models (optional) → vehicle id → details

Quick examples

Common requests (not every endpoint). For full reference + schemas, open the Postman docs.

Full API reference
Postman

This page is a quick start. For the complete endpoint list + schemas, use your Postman docs.

Open Postman docs

Response format

Most picker endpoints return simple arrays. Details endpoints return a structured object.

Example: Years
Response 
[2026, 2025, 2024, 2023]
Example: Makes
Response 
["Toyota", "Honda", "Ford"]
Example: Details

Field names can vary by dataset (automotive vs powersports). Treat this as a representative example.

Response 
{
    "id": "9f55fd34-a206-4507-b1ee-6eb2eb9fab35",
    "type": "Automotive",
    "year": "2026",
    "make": "Chevrolet",
    "model": "Trailblazer",
    "subModel": "LT",
    "trim": "LT Sport Utility 4-Door",
    "engineLiter": "1.3L",
    "engine": "1.3L 1349CC 83Cu. In. l3 GAS DOHC Turbocharged",
    "bodyStyle": "Sport Utility",
    "engine_cylinders": "3",
    "cylinder_type": "DOHC",
    "engine_cc": "1349",
    "drive_type": "AWD",
    "fuel_type": "GAS",
    "number_doors": "4",
    "diaplay_name": "Chevrolet Trailblazer 2026 LT",
    "aspiration": "Turbocharged",
    "makeLogoUrl": "https://carlistapi.com/assets/img/car-logos/chevrolet.png"
}

Rate limits

If you exceed limits, the API returns 429. Your integration should back off and retry.

Avoid 429s in UI pickers

Cache picker endpoints and only request details once the user selects a final vehicle.

Example (429) 
{ "message": "Too many requests." }

Status codes

Quick meanings for common responses:

Common statuses
200
OK (success)
401
Missing/invalid token
403
Blocked (often IP restriction)
422
Validation or parameter format issue
429
Rate limit exceeded
500
Server error

Caching

For best performance, cache picker endpoints. Years/makes/models change infrequently compared to details.

Suggested TTLs
  • Years: 24h
  • Makes: 24h
  • Models: 6–24h
  • Trims/Engines: 6–24h
  • Details by UUID: 7d
Laravel example
Cache::remember 
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;

$years = Cache::remember('carlistapi:years', 86400, function () {
    return Http::withToken(config('services.carlistapi.token'))
        ->acceptJson()
        ->get('https://carlistapi.com/api/v1/car-data/get-years/asc')
        ->throw()
        ->json();
});

Demo endpoints

Use demo routes to prototype without touching production datasets. These endpoints do not require authentication.

Automotive demo years 
GET https://carlistapi.com/api/v1/car-data-demo/get-years-demo/asc
Automotive demo makes 
GET https://carlistapi.com/api/v1/car-data-demo/get-makes-demo/asc
Powersports demo years 
GET https://carlistapi.com/api/v1/powersports-data-demo/get-years-demo/asc
Powersports demo makes 
GET https://carlistapi.com/api/v1/powersports-data-demo/get-makes-demo/asc
When to use demo
  • Building UI pickers
  • Testing URL encoding and caching
  • Confirming request flow before going live

Authentication

Send your API token using the Authorization header.

cURL (Automotive years) 
curl -X GET "https://carlistapi.com/api/v1/car-data/get-years/asc" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Accept: application/json"
JavaScript (fetch) 
const res = await fetch("https://carlistapi.com/api/v1/car-data/get-years/asc", {
    headers: {
        Authorization: "Bearer YOUR_API_TOKEN",
        Accept: "application/json",
    },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);

Base URL

All v1.x endpoints are under:

Base URL 
https://carlistapi.com/api/v1

Automotive

Typical picker flow: years → makes → models → trims → engines → vehicle id → details

Years 
GET https://carlistapi.com/api/v1/car-data/get-years/asc
Makes by year 
GET https://carlistapi.com/api/v1/car-data/get-makes/{year}/asc
Models by year+make 
GET https://carlistapi.com/api/v1/car-data/get-models/{year}/{make}/asc
Trims 
GET https://carlistapi.com/api/v1/car-data/get-trims/{year}/{make}/{model}/asc
Engines 
GET https://carlistapi.com/api/v1/car-data/get-engines/{year}/{make}/{model}/{trim}/asc
Vehicle ID 
GET https://carlistapi.com/api/v1/car-data/get-vehicle-id/{year}/{make}/{model}/{trim}/{engine}
Details 
GET https://carlistapi.com/api/v1/car-data/get-details/{uuid}

Powersports

Typical picker flow: years → makes → models → sub-models → vehicle id → details

Years 
GET https://carlistapi.com/api/v1/powersports-data/get-years/asc
Makes by year 
GET https://carlistapi.com/api/v1/powersports-data/get-makes/{year}/asc
Models by year+make 
GET https://carlistapi.com/api/v1/powersports-data/get-models/{year}/{make}/asc
Sub-models 
GET https://carlistapi.com/api/v1/powersports-data/get-sub-models/{year}/{make}/{model}/asc
Vehicle ID 
GET https://carlistapi.com/api/v1/powersports-data/get-vehicle-id/{year}/{make}/{model}/{trim}
Details 
GET https://carlistapi.com/api/v1/powersports-data/get-details/{uuid}

Common mistakes

URL encoding

If make/model/trim/engine include spaces or slashes, URL-encode them.

Example 
Grand%20Vitara
Automotive vehicle-id requires engine

Automotive get-vehicle-id includes {engine}. Powersports uses a different signature.

Don’t call details on every keystroke

Use caching + call details only when the user finalizes a selection (keeps your app fast and avoids 429s).

Filtering

Typical picker filters include:

Common inputs
year
4-digit year (e.g. 2020)
make
Manufacturer (e.g. Toyota)
model
Model name (e.g. Camry)
trim
(Optional) Trim string

Error format

Errors return JSON with an HTTP status code (401, 403, 422, 429, 500, etc.).

Example (401) 
{ "message": "Unauthenticated." }

Try / Catch

Wrap requests so your app can gracefully handle invalid tokens, rate limits, or network failures.

PHP (Laravel Http::) try/catch 
use Illuminate\Support\Facades\Http;

try {
    $response = Http::withToken(config('services.carlistapi.token'))
        ->acceptJson()
        ->get('https://carlistapi.com/api/v1/car-data/get-years/asc');

    if ($response->unauthorized()) {
        abort(401, 'CarListAPI token is invalid.');
    }

    if ($response->status() === 403) {
        abort(403, 'Request blocked (check IP restrictions).');
    }

    if ($response->tooManyRequests()) {
        abort(429, 'Rate limit hit. Please retry shortly.');
    }

    $response->throw();
    $data = $response->json();

} catch (\Throwable $e) {
    report($e);
    abort(502, 'CarListAPI request failed.');
}
JavaScript (fetch) try/catch 
try {
    const res = await fetch("https://carlistapi.com/api/v1/car-data/get-years/asc", {
        headers: {
            Authorization: "Bearer YOUR_API_TOKEN",
            Accept: "application/json",
        },
    });

    if (res.status === 401) throw new Error("Invalid token");
    if (res.status === 403) throw new Error("Blocked (check IP restrictions)");
    if (res.status === 429) throw new Error("Rate limit hit");

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const data = await res.json();
    console.log(data);
} catch (err) {
    console.error("CarListAPI error:", err);
}