# Vehicle API — full API reference

Base URL: `https://vehicles-api.com/api/v1`

## Authentication

Send your API key on every request as the `X-API-Key` header (or `Authorization: Bearer <key>`). Keys come from the dashboard after signup; agents can self-issue a sandbox key via https://vehicles-api.com/auth.md.

## Response format

Success: `{"status":"success","source":"<provider>","data":{...}}`. Error: `{"status":"error","error":{"code":"<code>","message":"<human readable>"}}`.

| HTTP | code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, invalid, revoked or expired key |
| 403 | no_active_plan | The account has no active trial or subscription |
| 404 | not_found | No record (e.g. unknown Dutch plate) |
| 422 | invalid_vin / invalid_plate / invalid_vehicle | Bad or missing input: VINs are 17 characters without I, O or Q; /v1/recalls needs make, model and year |
| 422 | coverage_us_only | Valid VIN with no US-market NHTSA match: recalls, complaints and NCAP ratings do not apply (/vin/report still returns 200) |
| 429 | rate_limit_exceeded / quota_exceeded | Per-minute limit or monthly quota reached |
| 502 | upstream_unavailable | Government data source temporarily unavailable — retry with backoff |

Only 2xx responses count toward your quota; errors are never billed.

## Endpoints

### Decode — POST /v1/vin/decode

Year, make, model, trim, engine, transmission and assembly plant for any 17-character VIN.

Parameters (JSON body):
- `vin` (required) — 17 characters · letters I, O and Q are never used. Example: `1HGCM82633A004352`

Example request:
```
curl -X POST https://vehicles-api.com/api/v1/vin/decode \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin":"1HGCM82633A004352"}'
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "vin": "1HGCM82633A004352",
        "valid": true,
        "year": 2003,
        "make": "HONDA",
        "model": "Accord",
        "trim": "EX-V6",
        "body": "Coupe",
        "doors": 2,
        "vehicle_type": "PASSENGER CAR",
        "engine": {
            "cylinders": 6,
            "displacement_l": 3,
            "configuration": "V-Shaped",
            "model": "J30A4",
            "hp": 240,
            "fuel": "Gasoline"
        },
        "drive": null,
        "transmission": {
            "style": "Automatic",
            "speeds": 5
        },
        "plant": {
            "country": "UNITED STATES (USA)",
            "city": "MARYSVILLE",
            "state": "OHIO"
        },
        "manufacturer": "AMERICAN HONDA MOTOR CO., INC."
    }
}
```

### Full report — POST /v1/vin/report

Specs, open recalls, complaint count and crash ratings in a single call.

Parameters (JSON body):
- `vin` (required) — 17 characters · letters I, O and Q are never used. Example: `1HGCM82633A004352`

Example request:
```
curl -X POST https://vehicles-api.com/api/v1/vin/report \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin":"1HGCM82633A004352"}'
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "vin": "1HGCM82633A004352",
        "valid": true,
        "year": 2003,
        "make": "HONDA",
        "model": "Accord",
        "trim": "EX-V6",
        "body": "Coupe",
        "doors": 2,
        "vehicle_type": "PASSENGER CAR",
        "engine": {
            "cylinders": 6,
            "displacement_l": 3,
            "fuel": "Gasoline"
        },
        "plant": {
            "country": "UNITED STATES (USA)",
            "city": "MARYSVILLE",
            "state": "OHIO"
        },
        "manufacturer": "AMERICAN HONDA MOTOR CO., INC.",
        "coverage": "us",
        "recalls_count": 24,
        "recalls": [
            {
                "campaign": "19V182000",
                "component": "AIR BAGS:FRONTAL:DRIVER SIDE:INFLATOR MODULE",
                "received": "2019-03-06",
                "summary": "Replacement driver air bag inflator may explode.",
                "consequence": "Sharp metal fragments may strike occupants.",
                "remedy": "Dealers will replace the inflator, free of charge."
            }
        ],
        "complaints_count": 2013,
        "safety_ratings": {
            "match": "partial",
            "vehicle_description": "2003 Honda Accord 2-DR.",
            "overall": null,
            "front": {
                "driver": 5,
                "passenger": 5
            },
            "side": {
                "driver": 5,
                "passenger": 5
            },
            "rollover": 4
        }
    }
}
```

### Validate — POST /v1/vin/validate

Format and ISO 3779 check-digit validation, computed locally (no upstream call).

Parameters (JSON body):
- `vin` (required) — 17 characters · the 9th character is the check digit. Example: `1HGCM82633A004352`

Example request:
```
curl -X POST https://vehicles-api.com/api/v1/vin/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vin":"1HGCM82633A004352"}'
```

Example response:
```json
{
    "status": "success",
    "source": "local",
    "data": {
        "vin": "1HGCM82633A004352",
        "valid": true,
        "check_digit": "3"
    }
}
```

### Recalls — GET /v1/vin/recalls

Official NHTSA recall campaigns for the decoded year / make / model.

Parameters (query string):
- `vin` (required) — Matched by make + model + year: any vehicle sold in the US, wherever it was built. Example: `1HGCM82633A004352`

Example request:
```
curl "https://vehicles-api.com/api/v1/vin/recalls?vin=1HGCM82633A004352" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "vin": "1HGCM82633A004352",
        "year": 2003,
        "make": "HONDA",
        "model": "Accord",
        "coverage": "us",
        "count": 24,
        "recalls": [
            {
                "campaign": "19V182000",
                "component": "AIR BAGS:FRONTAL:DRIVER SIDE:INFLATOR MODULE",
                "received": "2019-03-06",
                "summary": "Replacement driver air bag inflator may explode.",
                "consequence": "Sharp metal fragments may strike occupants.",
                "remedy": "Dealers will replace the inflator, free of charge."
            }
        ]
    }
}
```

### Recalls by model — GET /v1/recalls

US-market NHTSA recall campaigns for a make, model and year — no VIN needed. Zero campaigns is a 200 with an empty list.

Parameters (query string):
- `make` (required) — Brand as sold in the US, case-insensitive. Example: `BMW`
- `model` (required) — US-market model name, as NHTSA lists it. Example: `320i`
- `year` (required) — 4-digit model year. Example: `2002`

Example request:
```
curl "https://vehicles-api.com/api/v1/recalls?make=BMW&model=320i&year=2002" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "year": 2002,
        "make": "BMW",
        "model": "320i",
        "coverage": "us",
        "count": 1,
        "recalls": [
            {
                "campaign": "20V018000",
                "component": "AIR BAGS:FRONTAL:PASSENGER SIDE:INFLATOR MODULE",
                "received": "2020-01-15",
                "summary": "BMW is recalling certain 2000-2006 3 Series vehicles equipped with Takata PSAN passenger frontal air bag inflators.",
                "consequence": "An inflator explosion may result in sharp metal fragments striking the driver or other occupants.",
                "remedy": "Dealers will replace the passenger front air bag, free of charge."
            }
        ]
    }
}
```

### Complaints — GET /v1/vin/complaints

Owner complaints filed with NHTSA ODI — the 50 most recent, plus the true total.

Parameters (query string):
- `vin` (required) — Matched by make + model + year: any vehicle sold in the US, wherever it was built. Example: `1HGCM82633A004352`

Example request:
```
curl "https://vehicles-api.com/api/v1/vin/complaints?vin=1HGCM82633A004352" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "vin": "1HGCM82633A004352",
        "year": 2003,
        "make": "HONDA",
        "model": "Accord",
        "coverage": "us",
        "count": 2013,
        "complaints": [
            {
                "odi_number": "11459899",
                "date": "2022-03-15",
                "crash": false,
                "fire": false,
                "injured": 0,
                "deaths": 0,
                "components": [
                    "AIR BAGS"
                ],
                "summary": "Driver airbag warning light illuminated."
            }
        ]
    }
}
```

### Safety ratings — GET /v1/vin/safety-ratings

NHTSA NCAP crash-test stars: frontal, side and rollover.

Parameters (query string):
- `vin` (required) — Matched by make + model + year: any vehicle sold in the US, wherever it was built. Example: `1HGCM82633A004352`

Example request:
```
curl "https://vehicles-api.com/api/v1/vin/safety-ratings?vin=1HGCM82633A004352" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response:
```json
{
    "status": "success",
    "source": "nhtsa",
    "data": {
        "vin": "1HGCM82633A004352",
        "coverage": "us",
        "match": "partial",
        "vehicle_description": "2003 Honda Accord 2-DR.",
        "overall": null,
        "front": {
            "overall": null,
            "driver": 5,
            "passenger": 5
        },
        "side": {
            "overall": null,
            "driver": 5,
            "passenger": 5
        },
        "rollover": 4,
        "nhtsa_vehicle_id": 4736
    }
}
```

### Netherlands — POST /v1/plate/nl

Dutch RDW registration record for a kenteken (plate). RDW data never includes the VIN.

Parameters (JSON body):
- `plate` (required) — With or without dashes — K-875-HJ works too. Example: `K875HJ`

Example request:
```
curl -X POST https://vehicles-api.com/api/v1/plate/nl \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plate":"K875HJ"}'
```

Example response:
```json
{
    "status": "success",
    "source": "plate_nl",
    "data": {
        "plate": "K875HJ",
        "vin": null,
        "year": 2021,
        "make": "TOYOTA",
        "model": "AYGO",
        "body": "hatchback",
        "color": "GRIJS",
        "doors": 4,
        "seats": 4,
        "vehicle_type": "Personenauto",
        "engine": {
            "cylinders": 3,
            "displacement_cc": 998,
            "fuel": "Benzine"
        },
        "mass_kg": 815,
        "apk_expires": "2027-01-04",
        "first_registration": "2021-01-04",
        "open_recall": false
    }
}
```

### United States — POST /v1/plate/us

Plate + state → VIN → specs, via a plate-to-VIN vendor. Returns upstream_unavailable until a vendor key is configured.

Parameters (JSON body):
- `plate` (required) — No spaces. Example: `7ABC123`
- `state` (required) — USPS 2-letter code. Example: `CA`

Example request:
```
curl -X POST https://vehicles-api.com/api/v1/plate/us \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plate":"7ABC123","state":"CA"}'
```

Example response:
```json
{
    "status": "success",
    "source": "plate_us",
    "data": {
        "plate": "7ABC123",
        "state": "CA",
        "vin": "1HGCM82633A004352",
        "year": 2003,
        "make": "HONDA",
        "model": "Accord",
        "trim": "EX-V6",
        "body": "Coupe",
        "vehicle_type": "PASSENGER CAR"
    }
}
```

### US states — GET /v1/plate/us/states

The US states (USPS codes) covered by plate lookups. Static reference data.

Example request:
```
curl "https://vehicles-api.com/api/v1/plate/us/states" \
  -H "X-API-Key: YOUR_API_KEY"
```

Example response:
```json
{
    "status": "success",
    "source": "plate_us",
    "data": {
        "states": [
            {
                "code": "AL",
                "name": "Alabama"
            },
            {
                "code": "AK",
                "name": "Alaska"
            },
            {
                "code": "…",
                "name": "51 entries in total"
            }
        ]
    }
}
```

## Plans

| Plan | Monthly | Yearly | Requests/month | Requests/minute |
|---|---|---|---|---|
| Starter | $49.00 | $470.00 | 50,000 | 100 |
| Pro | $199.00 | $1,910.00 | 250,000 | 500 |

Every plan starts with a 7-day free trial (50 requests during the trial). Quotas reset monthly.

## MCP server

Setup guide: https://vehicles-api.com/mcp

Streamable HTTP endpoint: `https://vehicles-api.com/mcp` (POST, JSON-RPC 2.0). Authenticate with `Authorization: Bearer <API key>`. `initialize` and `tools/list` are free; each `tools/call` counts as one API request.