# Changelog

Changes to the AutoUncle Data Services API, MCP server, documentation and agent skill, newest first. AutoUncle Data Services is in **beta**: until contract version 1.0 the API, MCP tools and agent skill may change often, including breaking changes. Every change is announced here first.

The current contract version is in the [OpenAPI document](/openapi.yaml) (`info.version`) and in the MCP server's `serverInfo.version`.

## Unreleased · Market & demand

- **`POST /v1/market`** and the MCP tool **`get_market`**. Send the same vehicle input as a valuation (a make and model are enough) and get the market for that car type in one country: listings on sale, asking price and mileage (5th percentile, median, 95th percentile), model years, the price-rating mix and the share with a lowered price; listings leaving the market per day; median and mean days to leave; days of supply, turnovers per year and a demand level against the whole market; and a 12-month trend of listings leaving the market, days to leave and last asking price. See [market & demand](/docs/reference/market).
- **The same segment as the similar-cars link.** `segment.similar_cars_url` opens the listings the figures describe on the market's own AutoUncle site.
- **Aggregates only.** No listing is returned. A figure built from fewer than 10 listings is withheld and named in `suppressed`, and prices and mileage are rounded. "Left the market" means removed from sale, which is not always a sale; a `market_figures_describe_listings` note says so. Every market, Denmark included.
- **One credit** for a `measured` live result. `partial` (a data store could not answer) and `insufficient_data` results are free, as are test keys, which get deterministic example figures. Nothing is stored: an idempotent replay reads the market again for free.
- **Market & demand in the console.** The APIs page groups market & demand and selling-time forecasts under one Market & demand service. The playground runs `POST /v1/market` over REST and MCP. `POST /v1/selling-times` is unchanged.

## Unreleased · Trade-in price, link to similar cars, five comparables per group

- **`options.include: ["trade_in_price"]`** (valuations and selling-time forecasts, REST and MCP). A `valued` result gets `trade_in_price`: AutoUncle's estimate of a fair price for a dealer to pay when taking the vehicle in trade, with `price`, `low`, `high` and `currency`. It is an estimate, not an offer, and a `trade_in_price_is_estimate` note says so. It always relates to the vehicle's dealer retail market value, also when the valuation uses `price_basis: "private_sale"`. See [trade-in price](/docs/valuations#trade-in-price).
- **Twelve markets.** Available in AT, CH, DE, DK, ES, FR, GB, IT, NL, PL, PT and SE. Elsewhere (FI, RO, and BE on request) it is `unavailable` with `unavailable_reason: "market_unsupported"` and a `trade_in_price_unavailable_in_market` note.
- **One extra credit**, reserved with the valuation and captured only when the trade-in price is returned (`usage.charges.trade_in_price`). A request can now cost up to four credits (`usage.credits_used` at most 4). Test keys get a fixed synthetic example for free.
- **`options.include: ["similar_cars_link"]`** adds `similar_cars_url`: a link to similar cars for sale on the market's own AutoUncle site, in the market's language. Free, in every market including Denmark. See [link to similar cars](/docs/valuations#link-to-similar-cars).
- **Comparables: up to five per group.** `comparables.on_sale` and `comparables.recently_sold` now hold up to five listings each (was three). Selection, rounding, fields, price and Denmark are unchanged.

## Unreleased · Selling-time forecasts in every market

- **Every Data Services market.** `POST /v1/selling-times` and the MCP tool `forecast_selling_time` now forecast in every market with `general` availability, not only Denmark and Sweden. `selling_time_unsupported_market` is now only returned for a country Data Services does not serve to every workspace, such as Belgium. If a market's forecast model is temporarily missing, the request fails with `selling_time_unavailable` (503) and nothing is charged. See [selling-time forecasts](/docs/selling-time#markets).
- **Console.** The playground runs selling-time forecasts over REST and MCP and shows the forecast for each price-rating band and your asking price. The Selling-time forecast card on the APIs page has a Try it button.

## Contract 0.9.0 · Vehicles as AVS documents

**Breaking** for every result that describes a vehicle: `POST /v1/valuations`, `GET /v1/valuations/{id}`, `POST /v1/vehicles/normalize`, `/decode`, `/hsn-tsn` and `/lookup`, and the MCP tools `valuate_car`, `get_valuation`, `normalize_vehicle`, `decode_vin`, `decode_hsn_tsn` and `lookup_plate`. Comparables and the catalogue endpoints are unchanged.

- **`vehicle` is an AVS document.** It is now an [AutoUncle Vehicle Schema (AVS)](https://github.com/AutoUncle/avs) 0.3 `vehicle` document, so any AVS tooling can validate and read it. It is sparse: only `avs` and `identity.brand` and `identity.model` are always present, unknown values are left out instead of `null` or empty, and a missing equipment feature means unknown. Catalogue IDs are in `ids` as `{ "scheme": "autouncle", "value": "dv-…" }`. See [the Vehicle object](/docs/reference/vehicles#the-vehicle-object).
- **`identification` beside it.** `status`, `level`, `catalogue_version` and `candidates` move to a new `identification` object (the variant text you sent is kept in `extensions["com.autouncle"].variant_text`), unchanged in shape. Its `fields` keep per-value provenance, now keyed by JSON Pointer into the AVS document, such as `/specification/powertrain/powerHp` or `/vehicle/odometer`. When a vehicle has no brand and model, `vehicle` is left out and `identification` says why. See [identification](/docs/reference/vehicles#identification).
- **Where values moved.** `identity.generation` is `identity.body` (with `type`, `fromYear` and `toYear`), `identity.equipment_variant` is `equipment.trim`, `specs` is `specification.body` and `specification.powertrain` (fuel as `energy` and `electrification`, power as `powerHp` and `powerKw`, engine size as `engine.displacementCc`, `4wd` as `awd`, `convertible` as `cabriolet`), `equipment[]` is `equipment.features[]`, `registration` is `vehicle.vin` and `vehicle.registration` (`plate`, `firstRegistrationDate`, `modelYear`, `originalCountry`, `isImported`), `listing.mileage` is `vehicle.odometer.km` in kilometres (with `readAt` for a register's reading) and `listing.colour` is `vehicle.colour`. Assumed equipment has `availability: "unknown"`.
- **`extensions["com.autouncle"]`** holds what AVS has no field for yet: `battery_kwh`, `electric_range_km`, doors above 6 and seats above 9, `production_year`, a `first_registration` without a full date, `hsn`, `tsn`, `condition_grade` and `variant_text`.
- **Requests.** `vehicle` (VehicleInput) accepts an AVS document, recognized by its `avs` member, so a returned vehicle can be posted back unchanged. Otherwise it takes VehicleAttributes: the loose attributes, and the pre-0.9.0 groups (`identity`, `specs`, `registration`, `listing`, `equipment`), still accepted for compatibility.
- **Stored results.** Valuations recorded before 0.9.0 are converted when read, so `GET /v1/valuations/{id}` and `get_valuation` return AVS for every result.

**Migrating.** Read the vehicle from its AVS paths and the status, candidates and provenance from `identification`; a [mapping table](/docs/reference/vehicles#vehicleinput-describing-a-vehicle) lists every path. Re-key any stored provenance pointers. Requests need no change: the attributes you send today still work, and a stored pre-0.9.0 Vehicle can still be posted back.

- **Account markets (documentation correction).** `allowed_countries` in `GET /v1/account` and `get_account` lists the markets the calling key can value, as the ISO codes requests use in `country` (`DK`, `GB`, `DE`), narrowed by the key's own allowed countries, and lists every market when nothing restricts them. The API already worked this way; the documentation wrongly described AutoUncle's internal codes (`da`, `uk`) and the workspace's list only. See [account](/docs/reference/account#market-codes-in-allowed_countries).

## Contract 0.9.0 · Alloy wheels from photos

- **Alloy wheels.** Photos are now also read for alloy wheels. A car whose photos show them gets `WHEELS_ALLOY` in `vehicle.equipment.features`, with `source: ai_vision` in `identification.fields`. The valuation does not price alloy wheels, so the price is unchanged.

## Contract 0.9.0 · Image processing costs one extra credit

- **Photos cost one extra credit** (valuations and normalizations, REST and MCP). A live request that sends `images` reserves one more credit, per request however many photos. It is captured only when the request succeeds and a value in `identification.fields` was read from the photos (source or catalogue pick `ai_vision`); photos that were skipped or added nothing (`images_not_used`) are not charged. `usage.charges.images` shows it. A balance that cannot cover it rejects the request with `402 insufficient_credits`. Test keys never process photos and stay free.

## Contract 0.9.0 · Selling-time forecasts

- **`POST /v1/selling-times`** (REST, and the MCP tool `forecast_selling_time`). Values the vehicle as `POST /v1/valuations` does and adds `selling_time`: median days to sell and the chance of selling within 30, 60 and 90 days, for an asking price in the middle of each price-rating band and at `pricing.asking_price` when it is sent. See [selling-time forecasts](/docs/selling-time).
- **Denmark and Sweden.** Other markets are refused with `selling_time_unsupported_market` before any credit is reserved.
- **Two credits.** A successful live forecast costs two credits, one for the valuation and one for the forecast. `usage.charges` itemises them as `base` and `selling_time`. If the forecast cannot be made, the request fails with `selling_time_unavailable` or `selling_time_timeout` and nothing is charged. Test keys return fixed synthetic forecasts for free.
- **Rounded, aggregate figures.** Whole days, chances in steps of 0.05 and example prices to three significant figures. A `selling_time_is_forecast` note explains what a forecast means, and live forecasts are attributed to the new first-party source `autouncle_selling_time_model` (role `selling_time_model`).
- **Read back as a valuation.** A forecast's ID (`stf_…`) works with `GET /v1/valuations/{id}` and `get_valuation`, and the result keeps `object: "valuation"`.

## Contract 0.9.0 · Comparable listings as evidence

- **`options.include: ["comparables"]`** (valuations, REST and MCP). A `valued` result gets a `comparables` section: up to three similar listings on sale and three that left the market in the last 30 days, from the valuation's own market, with the `criteria` they had to match. Each listing has top-level facts only: make, model, model year, rounded mileage, rounded asking price, AutoUncle's price rating and days on market. See [comparable listings](/docs/valuations#comparable-listings).
- **Nothing that identifies a listing.** Comparables never carry seller names, contact details or region, listing text, dates, links, registration plates, VINs, catalogue IDs or photos.
- **Evidence, not the basis.** Comparables are looked up after scoring and never change the price, intervals or precision. A `comparables_are_evidence` note says so, and live comparables are attributed to the new first-party source `autouncle_market_listings` (role `market_listings`).
- **Denmark.** Not available in the Danish market: `status: "unavailable"`, `unavailable_reason: "market_restricted"` and a `comparables_unavailable_in_market` note. A lookup that fails elsewhere gives `temporarily_unavailable` and a `comparables_unavailable` warning, and the valuation is still `valued`.
- **One extra credit, only when delivered.** A live valuation with comparables reserves two credits. The second is captured only when listings are returned (`status: "included"`) and released for `none_found`, `unavailable` and refused or failed valuations. A balance that cannot cover both rejects the request with `402 insufficient_credits`. Test keys get fixed synthetic comparables (`synthetic: true`) in every market where comparables are available; a Danish test request returns `market_restricted`, as a live one does.
- **`usage.charges`** (valuations, normalizations and vehicle lookups). What `original_credits_used` paid for: `base` for the request itself and one entry per add-on, such as `comparables`. Empty when nothing was charged.
- **`options.include` is validated.** It was a reserved list whose values were ignored; it now accepts only `comparables`, and any other value is rejected with `400 invalid_request`.

## Contract 0.9.0 · Assumed equipment, on request

- **`options.allow_equipment_estimation`** (valuations and normalizations, REST and MCP). Off by default. When `true`, equipment the request does not state is assumed: the catalogue's equipment for the identified trim when it is known, otherwise the equipment at least 70% of comparable vehicles have. Test keys use only the catalogue trim. See [assumed equipment](/docs/valuations#assumed-equipment).
- **Never against evidence.** Assumed equipment is only added. What you send, and what your description or photos state or deny, always wins; a no in the description is a no.
- **Labelled as an assumption.** Each assumed feature has `source: "imputed"` and `basis: "assumed"` in `identification.fields` and `availability: "unknown"` in `vehicle.equipment.features`, with an `equipment_assumed` warning and an `improve_precision` hint (reason `equipment_assumed`). It caps `precision.grade` at `low`, as an assumed mileage does. `equipment_not_assumed` says when nothing could be assumed.
- **Posting a Vehicle back.** Assumed equipment is not read as stated equipment when you post a returned Vehicle back: in an AVS document only `availability: "fitted"` features count, and a pre-0.9.0 Vehicle whose `fields` mark equipment as assumed gets `assumed_equipment_ignored`. With the option on, it is assumed again and stays labelled.
- **Console.** The playground form has a checkbox for it, next to the mileage baseline.

## Contract 0.9.0 · Photos read into the Vehicle

- **What photos show.** With a live key and AI enabled, photos are read whenever you send them, even when the rest of the request identifies the vehicle. Besides identity, they now fill the Vehicle's `equipment.features` (as feature keys, for features a photo can show such as towbars, roofs, headlights, upholstery, sport seats, head-up displays and digital cockpits), `vehicle.colour` (with its `family`), `extensions["com.autouncle"].condition_grade` and `specification.body.driveSide`. Each value has `source: "ai_vision"` in `identification.fields` and counts in the valuation.
- **Your values come first.** Photos fill only what your request and the description leave open. Equipment is only ever added. A condition is used only when the reading is confident, and is never graded above 3 ("well kept") from photos. Photo readings do not lower `precision.grade`.
- **An unreadable image no longer fails the request.** It is skipped with an `image_skipped` warning that names it (`/images/N`), and the other inputs are used. A temporarily unavailable image host or an image timeout still fails the request.
- **`vehicle.colour.family`** is now returned whenever the colour maps to a family.

## Contract 0.9.0 · Model release IDs and data support

- **`model.model_id`** is an opaque release identifier such as `dk-3f9a1c0b7e2d`: stable for one model release and different for the next, so you can still tell releases apart. Test results keep `sandbox-v1`.
- **`valuation.intervals[].method`** is `calibrated` or `estimated` (`synthetic` for test results).
- **`precision.data_support`** returns `comparable_vehicles`, a lower bound (0, 10, 30, 100, 300, 1000, 3000 or 10000), instead of counts per catalogue level.

## Contract 0.9.0 · Equipment as features

Breaking for the equipment of a returned Vehicle and for the `equipment` list of `GET /v1/catalogue/enums`.

- **Feature keys.** A returned Vehicle lists its equipment in `equipment.features`: `key` (such as `EXTERIOR_TOWBAR_FIXED`), `ids`, `name`, `category` and `availability: "fitted"`, instead of `{ "key": "has_tow_bar", "availability": "observed" }`. The key is the most specific feature the listing or your request states. These are the same keys as the AutoUncle Vehicle Schema's features.
- **Enums.** `GET /v1/catalogue/enums` lists the feature keys.
- **Requests.** `vehicle.equipment` takes the feature keys, and a returned Vehicle's equipment items can be posted back as they are. The earlier `has_*` keys are still accepted.

## Contract 0.8.0 · One Vehicle for every endpoint

Breaking for valuation results and normalization scopes; additive otherwise. Every endpoint that describes a vehicle now returns the same [Vehicle](/docs/reference/vehicles#the-vehicle-object), identified against the AutoUncle catalogue, and every request that describes a vehicle accepts it back.

- **One Vehicle.** Valuations, normalizations and lookups return one `Vehicle` object: `identity` (catalogue brand, model, generation with production years, drivetrain and equipment variant), `specs`, `equipment`, `registration`, `listing`, provenance per value in `fields` and competing catalogue records in `candidates`, with a `status` of `identified`, `partially_identified`, `ambiguous` or `unidentified`.
- **Valuation results (breaking).** `vehicle` in a valuation result is now that Vehicle instead of the identity levels with `model_year` and `mileage`. `inputs_used` and `inferred` are removed: where each value came from is in `vehicle.fields`, keyed by JSON Pointer, with `basis`, `source`, `source_id` and `status`. Read the registration year at `vehicle.registration.model_year` and the mileage at `vehicle.listing.mileage`.
- **VehicleInput.** `vehicle` in valuation and normalization requests accepts the canonical Vehicle groups (`identity`, `specs`, `registration`, `listing`, `equipment`) as well as the loose attributes (`make`, `model`, `fuel`, `power_hp`, `catalogue` IDs and so on), so a lookup or normalization result can be posted straight back. Read-only parts are ignored; when a canonical and a loose value disagree, the canonical one wins with a `vehicle_input_overridden` warning. `registration.hsn` and `registration.tsn` are looked up in the KBA type snapshot. See [VehicleInput](/docs/reference/vehicles#vehicleinput-describing-a-vehicle).
- **VIN decoding, HSN/TSN and plates.** `POST /v1/vehicles/decode` decodes a VIN, `POST /v1/vehicles/hsn-tsn` looks up German type codes in the Kraftfahrt-Bundesamt type snapshot, and `POST /v1/vehicles/lookup` looks a plate up in the Danish Motor Register (Denmark only; other countries return `lookup_country_unsupported`). What the source says is identified against the catalogue, so lookups return catalogue IDs, specs, candidates, `improve_precision` and `warnings`, not just names. The MCP tools `decode_vin`, `decode_hsn_tsn` and `lookup_plate` return the same results. See [vehicle lookups](/docs/reference/vehicles#vehicle-lookups).
- **VIN and plate in valuations and normalizations.** With a live key, `vehicle.vin` and `vehicle.registration_plate` are looked up instead of ignored: plates and VINs in the Danish Motor Register (DK), VINs elsewhere by VIN decoding. Nothing is looked up in DE, IT or ES, or with test keys (`registry_lookup_not_used`). Looked-up values only fill what you left out; a disagreement gives a `registry_conflict` warning and your value is used. Looked-up values have `source: "registry"` and a `source_id` in `vehicle.fields`, and the source is listed in `attributions`. A lookup that cannot be used never blocks the request: `registry_lookup_not_available`, `registry_identifier_invalid`, `registry_no_match` or `registry_lookup_failed` says why. Only when the identifier was the request's sole description of the vehicle does a lookup timeout or outage fail it, with `service: "vehicle_registry"` and no charge. The lookup is included in the request's credit. See [VIN and registration plate](/docs/concepts/vehicle#vin-and-registration-plate).
- **Scopes, limits and billing.** Normalization and the lookups need the `vehicles:read` scope and share the vehicle rate limit (60 requests per minute by default); normalization needed `valuations:write` before. Existing keys must be edited or reissued to get `vehicles:read`. A live lookup that returns vehicle data costs one credit; `no_match`, failures and test keys are free. Test-key lookups return a fixed synthetic record with `synthetic: true` and a `synthetic_example` note. Request logs show lookups with the `succeeded` status.

## Contract 0.7.0 · Internal

Contract 0.7.0 was an internal version and was never published, so there are no public changes to report; its work shipped in 0.8.0.

## Contract 0.6.0 · Contract fixes

Mostly additive. Two changes alter what an existing request gets back: a request without `country` returns `country_required` instead of `invalid_request`, and the MCP `get_account` and `get_valuation` tools are now rate limited.

- **Catalogue and account response schemas.** Every catalogue endpoint and `GET /v1/account` has a complete response schema with field descriptions in the [OpenAPI document](/openapi.yaml). The [catalogue](/docs/reference/catalogue) and [account](/docs/reference/account) reference tables are generated from it.
- **`X-Valuation-Id` header.** Valuation results from `POST /v1/valuations` and `GET /v1/valuations/{id}` carry the `val_…` ID in `X-Valuation-Id`, the same value as the body's `request_id`. `X-Request-Id` stays the HTTP request ID on every response. See [response headers](/docs/api-reference#response-headers).
- **Country availability.** Each entry of `GET /v1/catalogue/countries` has `availability`: `general` for markets enabled for every new workspace, `on_request` for markets AutoUncle enables on request (currently Belgium). See [markets](/docs/concepts/markets).
- **`country_required`.** A valuation request with a missing or `null` `country` returns `400 country_required`, pointing at `/country`, instead of `400 invalid_request`.
- **MCP rate limits.** `get_account` and `get_valuation` count against the valuation rate limit like their REST equivalents and return `rate_limited` with `retry_after` and `isError: true` when it is reached.
- **`missing_mileage` wording.** A recorded refusal now has the same `detail` and `fix` steps as the [error reference](/docs/errors#missing_mileage).
- **Flags.** The ten `vehicle.flags` with an effect are documented keys in the contract. Other flag names give a `flags_not_recognized` warning, and a market-specific flag sent for another market gives `flags_not_applicable`. Unknown flags are still accepted. See [flags](/docs/concepts/vehicle#flags).

## 26 October 2026 · Documentation

- New documentation structure: Get started, Guides, API reference, MCP & agents, Concepts, Errors and this changelog, with search, page outlines and previous/next links.
- A step-by-step [quickstart](/docs/quickstart) and a [production checklist](/docs/production-checklist).
- API reference pages for [valuations](/docs/reference/valuations), the [catalogue](/docs/reference/catalogue) and the [account](/docs/reference/account), generated from the OpenAPI contract, with every request and response field, examples and errors per endpoint.
- Every [error code](/docs/errors#error-codes) with its recovery steps, generated from the error catalogue. Error `type` URLs now link to the code's own section.
- Install guides for Claude Code, Claude Desktop and claude.ai, Cursor, VS Code, ChatGPT and the OpenAI API, Gemini, Windsurf and other MCP clients, and a generated [MCP tool reference](/docs/mcp/tools).
- An expanded [agent skill](/docs/skill), downloadable as a package.
- Documentation code samples can open in the console playground.

## Contract 0.5.0 · Concurrency limits

Additive.

- Valuations run with limited concurrency per workspace, per market and across the platform. When no slot frees up within about two seconds, a request is rejected before anything is reserved, charged or recorded: `429 concurrency_limited` for your workspace, `503 engine_busy` for a market or the platform. Both are retryable with the same idempotency key. See [rate & concurrency limits](/docs/concepts/limits).
- Problems gain an optional `retry_after` field (seconds), which equals the REST `Retry-After` header and is the only retry delay over MCP. `rate_limited` now carries it too.
- If the limiter is unavailable, valuations fail closed with retryable `503 rate_limit_unavailable`.
- Refusals decided after scoring, such as `precision_below_minimum`, now record the `model` that scored them.
- A misrouted market scorer is reported as `503 engine_misconfigured` (not retryable) instead of a temporary outage.
- Every error code now has at least one recovery step in `fix`.

## Contract 0.4.0 · Notes, attributions and provenance basis

- Every valuation, catalogue and account result, over REST and MCP, carries `notes` (standing limitations, disclaimers and legal notices) and `attributions` (only the data sources that contributed, with licence references and any required attribution text). Both are always present and never truncated. See [notes & data sources](/docs/notices).
- Identity levels and `inputs_used`/`inferred` items gain a `basis`: `observed`, `extracted`, `catalogue` or `assumed`.
- Values interpreted by AI are no longer hinted as `imputed`; their improvement hint has reason `ai_interpreted`.
- Stored read-backs and idempotent replays return the notices that applied when the valuation was produced.

## Contract 0.2.0 to 0.3.0 · Explicit mileage, shared errors and dependency budgets

- **Missing mileage is refused by default** with `422 missing_mileage`. Set `options.allow_mileage_estimation: true` to opt in to a disclosed fixed 96,000 km baseline with low precision. Strict resolution still refuses missing mileage. Actual zero mileage is valid.
- Request errors and recorded refusals and failures share one error format with `code`, `detail`, `errors`, `fix`, `retryable`, `request_id`, `billable: false` and, for dependency failures, `service` and `reason`.
- Scorer timeout, outage and invalid response are distinguished as 504, 503 and 502.
- Failed and refused MCP tool results are flagged with `isError: true` and keep their structured payload.
- One processing budget covers interpretation, images and scoring. An invoked dependency that times out, is unavailable or returns invalid output stops the valuation and releases the credit, instead of being treated as missing evidence.

## Contract 0.1.0 · Internal

Contract 0.1.0 was an internal version and was never published, so there are no public changes to report.

## Developer preview

The first preview brought together the valuations and catalogue APIs, the account endpoint, the Data MCP server with API-key and OAuth access, free test keys, signup credits, the developer console (API keys, playground, request logs, usage, billing and team management) and this documentation.
