# CarAPI.dev Documentation

> Complete API documentation for CarAPI.dev - the Automotive Data API Platform.

## Complete API Reference

For full API documentation with all parameters, code examples (cURL, JavaScript, Python), and response schemas in a single file, see:
**[llms-full.txt](https://carapi.dev/llms-full.txt)**

This documentation site provides detailed guides, code examples, and reference material for integrating CarAPI.dev's automotive data APIs into your applications.

## Developer Resources

Machine-readable integration assets for tooling, code generation, and import into API clients:

- **OpenAPI 3.1 Specification**: [https://api.carapi.dev/openapi.json](https://api.carapi.dev/openapi.json) — complete schema for all endpoints with request/response shapes, parameters, and error formats. Import into Postman, Insomnia, OpenAPI Generator, or any spec-compatible tool.
- **Postman Workspace**: [https://www.postman.com/andurit/carapi-dev](https://www.postman.com/andurit/carapi-dev) — public Postman workspace with pre-built collection and environments (Production + Local). Fork the workspace, paste your API key into the `apiKey` environment variable, and send your first request.

## API Overview

Base URL: `https://api.carapi.dev/v1/`

All requests require authentication via the `token` query parameter.

## Endpoints

### VIN Decode
- **URL**: [/endpoints/vin-decode](https://docs.carapi.dev/endpoints/vin-decode)
- **Endpoint**: `GET /v1/vin-decode/:vin`
- **Description**: Decode a Vehicle Identification Number (VIN) to retrieve detailed vehicle specifications including make, model, engine power, transmission, fuel type, body style, drivetrain, color, and manufacturer details (name, region, country).

### Plate to VIN
- **URL**: [/endpoints/plate-to-vin](https://docs.carapi.dev/endpoints/plate-to-vin)
- **Endpoint**: `GET /v1/plate-to-vin/:plateNumber`
- **Description**: Convert a license plate number to its corresponding VIN. Supports PL, NO, SK, SE, CZ, and US. US lookups require a 2-letter `state` query parameter (US plates are only unique per state).

### Stolen Vehicle Check
- **URL**: [/endpoints/stolen-vehicle-check](https://docs.carapi.dev/endpoints/stolen-vehicle-check)
- **Endpoint**: `GET /v1/stolen-check/:vin`
- **Description**: Check if a vehicle has been reported as stolen in national and international databases.

### Vehicle Inspection
- **URL**: [/endpoints/vehicle-inspection](https://docs.carapi.dev/endpoints/vehicle-inspection)
- **Endpoint**: `GET /v1/inspection/:vin`
- **Description**: Retrieve vehicle inspection history including MOT tests, emissions checks, and safety inspections.

### Vehicle Listing
- **URL**: [/endpoints/vehicle-listing](https://docs.carapi.dev/endpoints/vehicle-listing)
- **Endpoint**: `GET /v1/listing`
- **Description**: Search current vehicle listings on the market. Filter by make, model, year, price range, and location.

### Vehicle Photos
- **URL**: [/endpoints/vehicle-photos](https://docs.carapi.dev/endpoints/vehicle-photos)
- **Endpoint**: `GET /v1/photos/:vin`
- **Description**: Retrieve available photos for a specific vehicle including exterior, interior, and detail shots.

### Vehicle Payments
- **URL**: [/endpoints/vehicle-payments](https://docs.carapi.dev/endpoints/vehicle-payments)
- **Endpoint**: `GET /v1/payments/:vin`
- **Description**: Get estimated monthly payment calculations based on vehicle price, down payment, loan term, and interest rate.

### Vehicle Valuation
- **URL**: [/endpoints/vehicle-valuation](https://docs.carapi.dev/endpoints/vehicle-valuation)
- **Endpoint**: `GET /v1/vehicle-valuation?make=<MAKE>&model=<MODEL>&year=<YEAR>&country=<ISO2>`
- **Description**: Get current market valuation for a vehicle by make/model/year/country (all required; `country` is ISO 3166-1 alpha-2, 24 supported). Optional `fuel` (`petrol`, `diesel`, `electric`, `hybrid`, `lpg`, `cng`, `hydrogen`) and `kw` (0-2000) filters narrow to a specific drivetrain variant. Optional `mileage` (0-1,000,000 km) refines the valuation for the supplied vehicle. Applied filters are echoed back on the response. Prices are returned in the market's local currency — USD for US, EUR for all other supported markets. Returns 404 when no valuation is available for the supplied configuration.

### Mileage History
- **URL**: [/endpoints/mileage-history](https://docs.carapi.dev/endpoints/mileage-history)
- **Endpoint**: `GET /v1/mileage-history/:vin`
- **Description**: Track historical mileage records for a vehicle to detect odometer rollbacks or inconsistencies.

### VIN OCR (Image)
- **URL**: [/endpoints/extract-vin](https://docs.carapi.dev/endpoints/extract-vin)
- **Endpoint**: `POST /v1/extract-vin`
- **Description**: Extract a 17-character VIN from a photo of a windshield etching, dashboard plate, door jamb sticker, or registration document. Accepts a base64-encoded image (15 MB body limit). Returns `{ vin, confidence }`; a 200 with `vin: null` means no VIN was found.

### License Plate OCR (Image)
- **URL**: [/endpoints/extract-plate](https://docs.carapi.dev/endpoints/extract-plate)
- **Endpoint**: `POST /v1/extract-plate`
- **Description**: Extract a license plate string from a vehicle photo. Optional `country` field (27 supported regions: sk, cz, de, at, pl, hu, ro, bg, hr, si, rs, fr, gb, it, es, pt, be, nl, se, no, dk, fi, ch, ie, gr, us, ca) enforces region-specific format validation. Returns `{ plateNumber, confidence }`; a 200 with `plateNumber: null` means no plate was found.

### Recalls
- **URL**: [/endpoints/recalls](https://docs.carapi.dev/endpoints/recalls)
- **Endpoint**: `GET /v1/recalls?make=<MAKE>&model=<MODEL>&modelYear=<YEAR>`
- **Description**: Look up U.S. recall records for a given make / model / year. Returns recall summaries, consequence, remedy, and severity flags (`parkIt`, `parkOutside`, `overTheAirUpdate`). Results are cached server-side.

### EV Charging Stations
- **URL**: [/endpoints/charging-stations](https://docs.carapi.dev/endpoints/charging-stations)
- **Endpoint**: `GET /v1/charging-stations?lat=<LAT>&lon=<LON>`
- **Description**: Nearest-N EV charging station search around a coordinate pair. Required: `lat` (-90..90), `lon` (-180..180). Optional: `radius` (km, default 10, max 50), `connectorType` (`type2` | `ccs` | `chademo`), `owner` (case-insensitive operator substring, e.g. "ionity"), `minPowerKw` (> 0), `limit` (default 5, max 10). Returns physical locations sorted by great-circle (straight-line, NOT driving) distance, each with address, owners, per-connector-type summaries (`maxPowerKw`, `minPricePerKwh` in EUR — often null, `plugs`), and `stationCount` (charge points merged into the location). No pagination by design. European coverage (strongest: IT, DE, NL, AT, BE, FR, CZ, PL, HU, RO, SK); data refreshes monthly.

## Account & Usage (Free — Not Billed)

These introspection endpoints never debit a credit. They require an API token (`?token=`) and are rate-limited rather than quota-billed.

### Account
- **URL**: [/account](https://docs.carapi.dev/account)
- **Endpoint**: `GET /v1/account?token=<API_KEY>`
- **Description**: Read your account's plan, status and live usage (`used`, `limit`, `remaining`, `resetDate`) plus your per-minute rate limit, in one response. Free — never spends a credit, and keeps returning 200 even when your monthly quota is exhausted so you can read your balance and reset date. Rate-limited to 1 request/second per account (burst 5). Never cached (`Cache-Control: no-store`).

### Endpoints Catalog
- **URL**: [/endpoints](https://docs.carapi.dev/endpoints)
- **Endpoint**: `GET /v1/endpoints?token=<API_KEY>`
- **Description**: List every active endpoint with its per-call credit cost (`slug`, `name`, `category`, `description`, `creditCost`). Free — never spends a credit. Identical for everyone and cacheable (`Cache-Control: public, max-age=300`).

## Authentication Example

```bash
curl -X GET "https://api.carapi.dev/v1/vin-decode/1HGBH41JXMN109186?token=your_api_token"
```

## Response Format

All endpoints return JSON responses with consistent structure:

```json
{
  "success": true,
  "data": { ... },
  "requestId": "uuid"
}
```

## Error Handling

Error responses include:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}
```

## Rate Limits

Rate limits are based on your subscription plan:
- Free: 100 requests/month
- Starter: 5,000 requests/month
- Professional: 25,000 requests/month
- Business: 100,000 requests/month

## Referral Credit (Lower Your Bill)

Customers can reduce their monthly bill by referring other developers via [carapi.dev/refer](https://carapi.dev/refer).

- **You earn**: €10 in **account credit** per qualified referral, applied automatically to your next CarAPI.dev invoice
- **Not cash**: this is invoice credit, not a cash payout — it cannot be withdrawn, transferred, or paid out to a bank/card; it is only redeemable against CarAPI.dev invoices
- **Friend gets**: 20% off their first invoice
- **When**: credit is granted when the referred user pays their first invoice (30-day refund clawback window)
- **Limit**: up to 10 successful referrals per rolling 12-month window
- **Free-plan users**: can earn credit; it is held on the account and applied automatically when they upgrade to a paid plan

## Market Coverage

CarAPI.dev has endpoint-specific country availability, strongest in Central/Eastern Europe.

### Global Endpoints (No Restrictions)

- **VIN Decode**: Any valid 17-character VIN (post-1981)
- **Mileage History, Vehicle Listing, Vehicle Photos, Vehicle Payments**: Global

### Vehicle Valuation (24 Countries)

CZ, SK, DE, AT, CH, FR, PL, RO, HU, HR, PT, BG, SI, RS, NL, LT, BE, ES, IE, IT, UK, NO, SE, US

### Vehicle Listing & Valuation - Supported Makes (40 total)

Both endpoints support 40 vehicle makes: Acura, Alfa Romeo, Audi, BMW, Cadillac, Chevrolet, Citroën, Cupra, Dacia, Dodge, Ferrari, Fiat, Ford, GMC, Honda, Hyundai, Jaguar, Jeep, Kia, Land Rover, Lexus, Mazda, Mercedes-Benz, MG, MINI, Mitsubishi, Nissan, Opel, Peugeot, Porsche, Ram, Renault, SEAT, Škoda, Subaru, Suzuki, Tesla, Toyota, Volvo, VW

Each make includes multiple models. See [llms-full.txt](https://carapi.dev/llms-full.txt) for complete model lists.

### Stolen Vehicle Check (5 Countries)

SK, CZ, SI, HU, RO

### Plate to VIN (6 Countries)

PL, NO, SK, SE, CZ, US (US requires a 2-letter state code)

### Vehicle Inspection

- **Available**: Slovakia (SK) - TK/EK records
- **Coming Soon**: Czech Republic (CZ), Germany (DE), United Kingdom (UK)

### EV Charging Stations (European Roaming Network)

Coverage across the European EV roaming network, strongest in IT, DE, NL, AT, BE, FR, CZ, PL, HU, RO, SK. ~54,000 physical charging locations; refreshed monthly.

## MCP Server (for AI Agents)

CarAPI is also available as a remote MCP (Model Context Protocol) server, exposing all REST endpoints plus a composite buyer-due-diligence tool to MCP-compatible clients (Claude Desktop, Claude Code, Claude.ai, Cursor, ChatGPT, Cline, Zed).

- **Endpoint**: `https://mcp.carapi.dev/mcp`
- **Transport**: Streamable HTTP (MCP spec 2025-03)
- **Auth**: `Authorization: Bearer <your-carapi-key>` (same key as the REST API)
- **Docs page**: [docs.carapi.dev/mcp](https://docs.carapi.dev/mcp)

Tool inventory: `carapi_vin_decode`, `carapi_plate_to_vin`, `carapi_stolen_check`, `carapi_inspection`, `carapi_listing_search`, `carapi_photos`, `carapi_payments`, `carapi_valuation`, `carapi_mileage_history`, `carapi_extract_vin` (image OCR), `carapi_extract_plate` (image OCR), `carapi_recalls` (US recalls), `carapi_buyer_report` (composite — costs 4 quota units), `carapi_docs` (search this documentation, no API key required, 60 req/min/IP).

## Main Website

Visit [carapi.dev](https://carapi.dev/) to sign up, manage your API keys, and view usage analytics.