Install and use the Car List API Laravel SDK

The Car List API Laravel SDK provides a Laravel-native client for the authenticated automotive, powersports, and VIN Decoder endpoints. It supports package auto-discovery, environment-based configuration, dependency injection, and a facade.

Initial SDK release: The Car List API Laravel SDK is currently at v0.1.0. Before the SDK reaches v1.0, package-level interfaces may evolve as we incorporate developer feedback. Review the package changelog and test dependency updates before deploying them to production. The SDK version is separate from the Car List API version (v1).

Should I use the Laravel or PHP SDK?

Use the Laravel SDK when your application runs Laravel 11, 12, or 13. It provides Laravel-specific configuration, service-container integration, and a facade.

For plain PHP, Symfony, Slim, WordPress, or another Composer-based application, use the Car List API PHP SDK instead.

Requirements

• PHP 8.2 or newer for Laravel 11 and 12

• PHP 8.3 or newer for Laravel 13

• Laravel 11, 12, or 13

• Composer

• An active Car List API token

Laravel 11 has reached the end of security support. Laravel 12 or newer is recommended for actively maintained applications.

Install the SDK

Run this command from your Laravel project:

composer require codebyray/carlistapi-laravel-sdk

Laravel package auto-discovery registers the service provider and facade automatically.

Configure your connection

Add these values to your application's .env file:

CAR_LIST_API_URL=https://carlistapi.com/api
CAR_LIST_API_VERSION=v1
CAR_LIST_API_TOKEN=your-api-token

The base URL must end with /api. Do not add /v1 to CAR_LIST_API_URL; the SDK appends the configured API version to each request.

Keep your token on the server. Do not commit it to source control, expose it in browser-side JavaScript, or include it in support requests.

If your application caches its configuration, clear the cache after changing these values:

php artisan optimize:clear

Publishing the package configuration is optional. If you need to customize it, run:

php artisan vendor:publish --tag=carlistapi-config

Make your first request

use CodebyRay\CarListApiLaravel\Facades\CarListApi;

$years = CarListApi::automotive()
    ->years()
    ->data;

You can also inject the manager through Laravel's service container:

use CodebyRay\CarListApiLaravel\CarListApiManager;
use Illuminate\Http\JsonResponse;

final class VehicleYearsController
{
    public function __invoke(CarListApiManager $carListApi): JsonResponse
    {
        $years = $carListApi->automotive()
            ->years()
            ->data;

        return response()->json($years);
    }
}

Automotive example

$makes = CarListApi::automotive()
    ->makes(2026)
    ->data;

$models = CarListApi::automotive()
    ->models(2026, 'Toyota')
    ->data;

$vehicle = CarListApi::automotive()
    ->details($vehicleUuid)
    ->data;

Powersports example

$types = CarListApi::powersports()
    ->types()
    ->data;

$models = CarListApi::powersports()
    ->modelsByYearMakeAndType('ATV / Utility', 2026, 'Can-Am')
    ->data;

VIN Decoder example

$vehicle = CarListApi::vinDecoder()
    ->decode('1HGCM82633A004352', modelYear: 2003)
    ->data;

The SDK normalizes spaces, hyphens, and letter casing before submitting the VIN.

Work with responses

Successful requests return an ApiResponse object. You can access its decoded data, HTTP status, and response headers:

$response = CarListApi::automotive()->years();

$data = $response->data;
$status = $response->status;
$remaining = $response->header('X-RateLimit-Remaining');

The SDK throws typed exceptions for authentication, authorization, validation, rate limits, missing records, server errors, and network failures. Catch the narrowest exception that your application can handle meaningfully, and avoid displaying raw exception details to end users.

Optional HTTP settings

CAR_LIST_API_TIMEOUT=15
CAR_LIST_API_CONNECT_TIMEOUT=5
CAR_LIST_API_RETRY_TIMES=2
CAR_LIST_API_RETRY_SLEEP_MS=200

Next steps

• Review the complete API documentation.

• View the Laravel SDK source and full reference.

• Create and manage API tokens from your Car List API dashboard.

• Report SDK-specific problems through the repository's issue tracker without including your API token.