# APIs at a glance

AutoUncle Data Services is a car valuation and vehicle data API for European markets: a handful of services behind one API key, covering market valuations, a car specifications database, a VIN decoder, HSN/TSN and licence plate lookup and vehicle data normalization. Each is a REST endpoint and, for agents, an MCP tool. They share authentication, errors, rate limits and the [Vehicle](/docs/concepts/vehicle) every vehicle endpoint returns. Only a successful live result uses credits: a valuation 1, plus 1 when requested comparables are returned and 1 when sent photos are used; a selling-time forecast 2; market & demand figures for a car type 1 when `measured`; VIN decoding, HSN/TSN and plate lookups and normalization 1 each when they return vehicle data (normalization +1 when photos are used). Catalogue and account calls are free, and test keys, refusals, failures and replays never use credits. See [credits](/docs/credits).

In the console, **APIs** lists the same services with your workspace's use of each, and **Usage** and **Request logs** filter by service or endpoint.

## Valuation

The market value of a used car in one European market. Send what you know about a car, from a full catalogue ID to a listing's text and photos, and get its market value with an 80% and 95% price range, a precision grade, price ratings and hints that would tighten the result. Read any recorded valuation back by its request ID.

- **Price:** 1 credit, +1 when requested comparables are returned, +1 when a requested trade-in price is returned, +1 when sent photos are used, per successful live result; test keys, refusals and failures are free.
- **Markets:** every market enabled for your workspace.
- **Key scope:** `valuations:write` and `valuations:read`.
- **MCP tools:** [`valuate_car`](/docs/mcp/tools#valuate_car) and [`get_valuation`](/docs/mcp/tools#get_valuation).
- **Reference:** [Valuation endpoints](/docs/reference/valuations).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`POST /v1/valuations`](/docs/reference/valuations#post-v1-valuations) | Resolve and value a vehicle | 1 |
| [`GET /v1/valuations/{id}`](/docs/reference/valuations#get-v1-valuations-id) | Retrieve your workspace’s recorded valuation | Free |

## Market & demand

How big the market for a car type is, how fast it moves, and how long one takes to sell. Describe the market for a car type: listings on sale, price and mileage ranges, the price-rating mix, how fast listings leave the market, days of supply, a demand level against the whole market and a 12-month trend. Forecast how long one specific car takes to sell at each price level.

- **Price:** Market & demand: 1 credit; Selling-time forecast: 2 credits, +1 when requested comparables are returned, +1 when a requested trade-in price is returned, per successful live result; test keys, refusals and failures are free.
- **Markets:** every market enabled for your workspace.
- **Key scope:** `valuations:write`.
- **MCP tools:** [`get_market`](/docs/mcp/tools#get_market) and [`forecast_selling_time`](/docs/mcp/tools#forecast_selling_time).
- **Reference:** [Market & demand endpoints](/docs/reference/market).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`POST /v1/market`](/docs/reference/market#post-v1-market) | Market and demand figures for a car type | 1 |
| [`POST /v1/selling-times`](/docs/reference/valuations#post-v1-selling-times) | Value a vehicle and forecast its selling time | 2 |

## Vehicle identification

Turn loose vehicle data, a VIN or a German type code into one catalogue vehicle. Normalize listing-style attributes into the AutoUncle Vehicle with field-by-field provenance, decode a VIN, or look up a German HSN/TSN type key. Each returns the same Vehicle, identified as far as the catalogue can, without valuing it.

- **Price:** Normalize: 1 credit, +1 when sent photos are used; VIN decode: 1 credit; HSN/TSN decode: 1 credit, per successful live result; test keys, refusals and failures are free.
- **Markets:** every market enabled for your workspace.
- **Key scope:** `vehicles:read`.
- **MCP tools:** [`normalize_vehicle`](/docs/mcp/tools#normalize_vehicle), [`decode_vin`](/docs/mcp/tools#decode_vin), and [`decode_hsn_tsn`](/docs/mcp/tools#decode_hsn_tsn).
- **Reference:** [Vehicle identification endpoints](/docs/reference/vehicles).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`POST /v1/vehicles/normalize`](/docs/reference/vehicles#post-v1-vehicles-normalize) | Resolve a vehicle without valuing it | 1 |
| [`POST /v1/vehicles/decode`](/docs/reference/vehicles#post-v1-vehicles-decode) | Decode a VIN into an AutoUncle vehicle | 1 |
| [`POST /v1/vehicles/hsn-tsn`](/docs/reference/vehicles#post-v1-vehicles-hsn-tsn) | Look up German HSN/TSN type codes | 1 |

## Licence-plate lookup

Look a registration plate up in the national vehicle register. Look up a car by its registration plate in the country's vehicle register and get the registered facts as a catalogue-identified Vehicle. Plates are only looked up where a register is connected.

- **Price:** 1 credit, per successful live result; test keys, refusals and failures are free.
- **Markets:** DK.
- **Key scope:** `vehicles:read`.
- **MCP tool:** [`lookup_plate`](/docs/mcp/tools#lookup_plate).
- **Reference:** [Licence-plate lookup endpoints](/docs/reference/vehicles).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`POST /v1/vehicles/lookup`](/docs/reference/vehicles#post-v1-vehicles-lookup) | Look up a vehicle by registration plate | 1 |

## Vehicle catalogue

Brands, models, generations, drivetrains and equipment variants, with their IDs. Browse and search the AutoUncle vehicle catalogue to build a picker or pin an exact vehicle, and read the values, markets and catalogue version the API accepts.

- **Price:** free.
- **Markets:** every market enabled for your workspace.
- **Key scope:** `catalogue:read`.
- **MCP tool:** [`search_vehicles`](/docs/mcp/tools#search_vehicles).
- **Reference:** [Vehicle catalogue endpoints](/docs/reference/catalogue).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`GET /v1/catalogue/search`](/docs/reference/catalogue#get-v1-catalogue-search) | Search makes and models | Free |
| [`GET /v1/catalogue/brands`](/docs/reference/catalogue#get-v1-catalogue-brands) | List vehicle makes | Free |
| [`GET /v1/catalogue/brands/{id}/models`](/docs/reference/catalogue#get-v1-catalogue-brands-id-models) | List models for a make | Free |
| [`GET /v1/catalogue/models/{id}/generations`](/docs/reference/catalogue#get-v1-catalogue-models-id-generations) | List generations for a model | Free |
| [`GET /v1/catalogue/generations/{id}/drivetrains`](/docs/reference/catalogue#get-v1-catalogue-generations-id-drivetrains) | List engine and transmission variants | Free |
| [`GET /v1/catalogue/brands/{id}/equipment-variants`](/docs/reference/catalogue#get-v1-catalogue-brands-id-equipment-variants) | List equipment variants | Free |
| [`GET /v1/catalogue/{kind}/{id}`](/docs/reference/catalogue#get-v1-catalogue-kind-id) | Get an item by catalogue UUID | Free |
| [`GET /v1/catalogue/enums`](/docs/reference/catalogue#get-v1-catalogue-enums) | List supported input values | Free |
| [`GET /v1/catalogue/countries`](/docs/reference/catalogue#get-v1-catalogue-countries) | List supported markets and mileage units | Free |
| [`GET /v1/catalogue/version`](/docs/reference/catalogue#get-v1-catalogue-version) | Get the catalogue version | Free |

## Account

Check a key, its scopes, markets and remaining credits. See which workspace a key belongs to, what it may do and where, and how many credits are left.

- **Price:** free.
- **Markets:** every market enabled for your workspace.
- **Key scope:** `account:read`.
- **MCP tool:** [`get_account`](/docs/mcp/tools#get_account).
- **Reference:** [Account endpoints](/docs/reference/account).

| Endpoint | What it does | Credits |
| --- | --- | --- |
| [`GET /v1/account`](/docs/reference/account#get-v1-account) | Inspect key permissions and available credits | Free |