# REST API reference

> For the complete documentation index, see [llms.txt](https://usecarscout.com/docs/llms.txt).

Public GET endpoints for CarScout market snapshots and VIN decoding. No key is required.

The REST API base URL is `https://api.usecarscout.com/api/v1`. The endpoints on this page are public and need no key. They answer with JSON.

The [OpenAPI description](https://usecarscout.com/openapi.json) covers the same endpoints.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/market/models` | Every tracked model, with its latest snapshot. |
| `GET` | `/market/models/MAKE_SLUG/MODEL_SLUG` | One model and each of its model years. |
| `GET` | `/market/models/MAKE_SLUG/MODEL_SLUG/YEAR` | The latest snapshot for one model year, with recalls, complaints, and fuel economy. |
| `GET` | `/market/models/MAKE_SLUG/MODEL_SLUG/YEAR/history` | Earlier snapshots for one model year. |
| `GET` | `/vehicle-data/decode-vin/VIN` | Decodes a VIN with NHTSA vPIC. |

Replace the following:

- `MAKE_SLUG`: the make in lowercase with hyphens, such as `toyota` or `land-rover`.
- `MODEL_SLUG`: the model in the same form, such as `rav4` or `grand-cherokee`.
- `YEAR`: the model year, such as `2021`.
- `VIN`: a 17-character VIN, or a partial VIN of 8 to 16 characters.

The slugs match the market pages on the site. For example, `https://usecarscout.com/market/toyota/rav4/2021` uses `toyota`, `rav4`, and `2021`.

## Get a model year snapshot

The following request gets the 2021 Toyota RAV4 snapshot:

```bash
curl https://api.usecarscout.com/api/v1/market/models/toyota/rav4/2021
```

The response has `model`, `modelYear`, and `snapshot`, plus recalls, complaints, and fuel economy. The `snapshot` object includes these fields:

```json
{
  "snapshotDate": "2026-10-18",
  "listingCount": 2064,
  "meanPrice": 24310,
  "medianPrice": null,
  "meanMileage": 75824,
  "medianMileage": 74714,
  "mileagePercentiles": {
    "p25": 53636,
    "p50": 74714,
    "p75": 95792
  },
  "stateCounts": {
    "CA": 4211,
    "TX": 3192
  }
}
```

Snapshots have no median price, so `medianPrice` is `null`. `meanPrice` is the average asking price for the model year.

AutoTrader reports mileage only as listing counts per 50,000-mile band. `meanMileage`, `medianMileage`, and `mileagePercentiles` are interpolated inside those bands, so they are accurate only to the band. For recent model years every listing falls in the first band, and the fields come out at 12,500, 25,000, and 37,500 regardless of the cars. Report the band, not the number. Newer snapshots also carry exact shares in `mileagePercentiles`: `under50k`, `under100k`, `under150k`, and `under200k` give the fraction of listings below each band edge.

## Decode a VIN

The following request decodes a VIN:

```bash
curl https://api.usecarscout.com/api/v1/vehicle-data/decode-vin/VIN
```

Replace `VIN` with the VIN to decode.

The response has `make`, `model`, `year`, `body_style`, `engine`, `transmission`, `drivetrain`, `fuel_type`, and `plant`. When NHTSA can't check the VIN's check digit, `valid` is `false`, and the other fields still hold what it decoded.

## Responses and errors

A successful response has `success: true` and the result in `data`. An error has `success: false`, a message in `error`, and a `code`:

```json
{
  "success": false,
  "error": "Model not found",
  "code": "NOT_FOUND"
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| `400 Bad Request` | `INVALID_VIN` | The VIN has the wrong length or characters. |
| `404 Not Found` | `NOT_FOUND` | No tracked model or model year matches the slugs. |
| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Too many requests from your IP address. |
| `500 Internal Server Error` | | CarScout couldn't answer. Try again later. |

## Rate limits

Each IP address can make 30 market requests a minute. Every response has `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. `X-RateLimit-Reset` is a Unix time in seconds.

The API doesn't allow cross-origin requests from browsers on other sites. Call it from your server, or use the MCP server.
