v1 · legacyPreserved docs for the previous API generation — v1 endpoints keep working, but new work should target v2. See v2 documentation.

Introduction

Comprehensive documentation for the Cardog v1 API — vehicle data, market analysis, and automotive insights.

Welcome to the Cardog API documentation. Our API provides comprehensive access to vehicle data, market insights, and automotive services. Whether you're building a dealership platform, market analysis tool, or automotive application, Cardog API offers the data and functionality you need.

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:
bash
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

Our API is designed with these principles in mind:

  • RESTful Design: Consistent resource-oriented URLs, proper HTTP methods, and standard status codes
  • Comprehensive Data: Deep vehicle information from trusted 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 include detailed information:

Example

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

The TypeScript client provides typed error handling:

typescript
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

If you're having trouble with the API, check out our API Status page. If you need further help, please contact support.

Next Steps