Legacy v1

Introduction

Last updated:

Documentation for the Cardog v1 API: vehicle data, market analysis, and automotive services.

Docs for the previous API generation. v1 endpoints keep working, but new work should target v2. See v2 documentation.

The Cardog API provides vehicle data, market analysis, and automotive services. It is built for dealership platforms, market analysis tools, and other automotive applications.

Deprecation

v1 is deprecated as of 2026-10-09 and stops answering on 2027-12-31. Every /v1 response says so in its headers: Deprecation (the date it took effect, as @ + unix seconds), Sunset (the date it stops), and a Link with rel="deprecation" pointing at the v2 documentation. Your key works on v2 unchanged; the changelog names every v2 operation by the date it arrived.

Getting Started

To start using the Cardog API:

  1. Create an account at cardog.app
  2. Create an API key in the API Keys section
  3. Install the official TypeScript client or use REST directly:
npm install @cardog/api
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: "your-api-key" });
const vehicle = await client.vin.decode("1HGCM82633A123456");
console.log(vehicle.variants[0].make, vehicle.variants[0].model);

API Principles

The API follows these conventions:

  • RESTful Design: Resource-oriented URLs, standard HTTP methods, and standard status codes
  • Comprehensive Data: Vehicle information from multiple sources
  • Real-time Updates: Current market data and pricing information

Authentication

All API requests require authentication using an API key. Include your key in the x-api-key header:

curl "https://api.cardog.app/v1/vin/12345678901234567" \
   -H "x-api-key: your-api-key"

See Authentication for key management, rate limits, and security best practices.

Error Handling

The API uses conventional HTTP response codes:

  • 200: Success
  • 400: Client errors (invalid requests)
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Server errors

Error responses have this shape:

Example

1 keys
"response": {
"error": {
"code": "invalid_vin",
"message": "The provided VIN is invalid",
"details": {2 items}
}
}

The TypeScript client provides typed error handling:

import { CardogClient, APIError } from "@cardog/api";

const client = new CardogClient({ apiKey: "your-api-key" });

try {
  const vehicle = await client.vin.decode("INVALID");
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.status);  // HTTP status code
    console.log(error.code);    // Error code (e.g., "INVALID_VIN")
    console.log(error.message); // Human-readable message
  }
}

Guides

API Reference

Troubleshooting

Check the API Status page first. If you still need help, contact support.

Next Steps

Was this helpful?