AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.
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 (info.version) and in the MCP server's serverInfo.version.
Unreleased · Market & demand
POST /v1/marketand the MCP toolget_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.- The same segment as the similar-cars link.
segment.similar_cars_urlopens 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; amarket_figures_describe_listingsnote says so. Every market, Denmark included. - One credit for a
measuredlive result.partial(a data store could not answer) andinsufficient_dataresults 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/marketover REST and MCP.POST /v1/selling-timesis 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). Avaluedresult getstrade_in_price: AutoUncle's estimate of a fair price for a dealer to pay when taking the vehicle in trade, withprice,low,highandcurrency. It is an estimate, not an offer, and atrade_in_price_is_estimatenote says so. It always relates to the vehicle's dealer retail market value, also when the valuation usesprice_basis: "private_sale". See 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
unavailablewithunavailable_reason: "market_unsupported"and atrade_in_price_unavailable_in_marketnote. - 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_usedat most 4). Test keys get a fixed synthetic example for free. options.include: ["similar_cars_link"]addssimilar_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.- Comparables: up to five per group.
comparables.on_saleandcomparables.recently_soldnow 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-timesand the MCP toolforecast_selling_timenow forecast in every market withgeneralavailability, not only Denmark and Sweden.selling_time_unsupported_marketis 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 withselling_time_unavailable(503) and nothing is charged. See selling-time forecasts. - 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.
vehicleis an AVS document. It is now an AutoUncle Vehicle Schema (AVS) 0.3vehicledocument, so any AVS tooling can validate and read it. It is sparse: onlyavsandidentity.brandandidentity.modelare always present, unknown values are left out instead ofnullor empty, and a missing equipment feature means unknown. Catalogue IDs are inidsas{ "scheme": "autouncle", "value": "dv-…" }. See the Vehicle object.identificationbeside it.status,level,catalogue_versionandcandidatesmove to a newidentificationobject (the variant text you sent is kept inextensions["com.autouncle"].variant_text), unchanged in shape. Itsfieldskeep per-value provenance, now keyed by JSON Pointer into the AVS document, such as/specification/powertrain/powerHpor/vehicle/odometer. When a vehicle has no brand and model,vehicleis left out andidentificationsays why. See identification.- Where values moved.
identity.generationisidentity.body(withtype,fromYearandtoYear),identity.equipment_variantisequipment.trim,specsisspecification.bodyandspecification.powertrain(fuel asenergyandelectrification, power aspowerHpandpowerKw, engine size asengine.displacementCc,4wdasawd,convertibleascabriolet),equipment[]isequipment.features[],registrationisvehicle.vinandvehicle.registration(plate,firstRegistrationDate,modelYear,originalCountry,isImported),listing.mileageisvehicle.odometer.kmin kilometres (withreadAtfor a register's reading) andlisting.colourisvehicle.colour. Assumed equipment hasavailability: "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, afirst_registrationwithout a full date,hsn,tsn,condition_gradeandvariant_text.- Requests.
vehicle(VehicleInput) accepts an AVS document, recognized by itsavsmember, 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}andget_valuationreturn AVS for every result.
Migrating. Read the vehicle from its AVS paths and the status, candidates and provenance from identification; a mapping table 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_countriesinGET /v1/accountandget_accountlists the markets the calling key can value, as the ISO codes requests use incountry(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.
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_ALLOYinvehicle.equipment.features, withsource: ai_visioninidentification.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
imagesreserves one more credit, per request however many photos. It is captured only when the request succeeds and a value inidentification.fieldswas read from the photos (source or catalogue pickai_vision); photos that were skipped or added nothing (images_not_used) are not charged.usage.charges.imagesshows it. A balance that cannot cover it rejects the request with402 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 toolforecast_selling_time). Values the vehicle asPOST /v1/valuationsdoes and addsselling_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 atpricing.asking_pricewhen it is sent. See selling-time forecasts.- Denmark and Sweden. Other markets are refused with
selling_time_unsupported_marketbefore any credit is reserved. - Two credits. A successful live forecast costs two credits, one for the valuation and one for the forecast.
usage.chargesitemises them asbaseandselling_time. If the forecast cannot be made, the request fails withselling_time_unavailableorselling_time_timeoutand 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_forecastnote explains what a forecast means, and live forecasts are attributed to the new first-party sourceautouncle_selling_time_model(roleselling_time_model). - Read back as a valuation. A forecast's ID (
stf_…) works withGET /v1/valuations/{id}andget_valuation, and the result keepsobject: "valuation".
Contract 0.9.0 · Comparable listings as evidence
options.include: ["comparables"](valuations, REST and MCP). Avaluedresult gets acomparablessection: 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 thecriteriathey 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.- 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_evidencenote says so, and live comparables are attributed to the new first-party sourceautouncle_market_listings(rolemarket_listings). - Denmark. Not available in the Danish market:
status: "unavailable",unavailable_reason: "market_restricted"and acomparables_unavailable_in_marketnote. A lookup that fails elsewhere givestemporarily_unavailableand acomparables_unavailablewarning, and the valuation is stillvalued. - 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 fornone_found,unavailableand refused or failed valuations. A balance that cannot cover both rejects the request with402 insufficient_credits. Test keys get fixed synthetic comparables (synthetic: true) in every market where comparables are available; a Danish test request returnsmarket_restricted, as a live one does. usage.charges(valuations, normalizations and vehicle lookups). Whatoriginal_credits_usedpaid for:basefor the request itself and one entry per add-on, such ascomparables. Empty when nothing was charged.options.includeis validated. It was a reserved list whose values were ignored; it now accepts onlycomparables, and any other value is rejected with400 invalid_request.
Contract 0.9.0 · Assumed equipment, on request
options.allow_equipment_estimation(valuations and normalizations, REST and MCP). Off by default. Whentrue, 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.- 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"andbasis: "assumed"inidentification.fieldsandavailability: "unknown"invehicle.equipment.features, with anequipment_assumedwarning and animprove_precisionhint (reasonequipment_assumed). It capsprecision.gradeatlow, as an assumed mileage does.equipment_not_assumedsays 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 whosefieldsmark equipment as assumed getsassumed_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 itsfamily),extensions["com.autouncle"].condition_gradeandspecification.body.driveSide. Each value hassource: "ai_vision"inidentification.fieldsand 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_skippedwarning 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.familyis now returned whenever the colour maps to a family.
Contract 0.9.0 · Model release IDs and data support
model.model_idis an opaque release identifier such asdk-3f9a1c0b7e2d: stable for one model release and different for the next, so you can still tell releases apart. Test results keepsandbox-v1.valuation.intervals[].methodiscalibratedorestimated(syntheticfor test results).precision.data_supportreturnscomparable_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 asEXTERIOR_TOWBAR_FIXED),ids,name,categoryandavailability: "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/enumslists the feature keys. - Requests.
vehicle.equipmenttakes the feature keys, and a returned Vehicle's equipment items can be posted back as they are. The earlierhas_*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, identified against the AutoUncle catalogue, and every request that describes a vehicle accepts it back.
- One Vehicle. Valuations, normalizations and lookups return one
Vehicleobject:identity(catalogue brand, model, generation with production years, drivetrain and equipment variant),specs,equipment,registration,listing, provenance per value infieldsand competing catalogue records incandidates, with astatusofidentified,partially_identified,ambiguousorunidentified. - Valuation results (breaking).
vehiclein a valuation result is now that Vehicle instead of the identity levels withmodel_yearandmileage.inputs_usedandinferredare removed: where each value came from is invehicle.fields, keyed by JSON Pointer, withbasis,source,source_idandstatus. Read the registration year atvehicle.registration.model_yearand the mileage atvehicle.listing.mileage. - VehicleInput.
vehiclein 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,catalogueIDs 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 avehicle_input_overriddenwarning.registration.hsnandregistration.tsnare looked up in the KBA type snapshot. See VehicleInput. - VIN decoding, HSN/TSN and plates.
POST /v1/vehicles/decodedecodes a VIN,POST /v1/vehicles/hsn-tsnlooks up German type codes in the Kraftfahrt-Bundesamt type snapshot, andPOST /v1/vehicles/lookuplooks a plate up in the Danish Motor Register (Denmark only; other countries returnlookup_country_unsupported). What the source says is identified against the catalogue, so lookups return catalogue IDs, specs, candidates,improve_precisionandwarnings, not just names. The MCP toolsdecode_vin,decode_hsn_tsnandlookup_platereturn the same results. See vehicle lookups. - VIN and plate in valuations and normalizations. With a live key,
vehicle.vinandvehicle.registration_plateare 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 aregistry_conflictwarning and your value is used. Looked-up values havesource: "registry"and asource_idinvehicle.fields, and the source is listed inattributions. A lookup that cannot be used never blocks the request:registry_lookup_not_available,registry_identifier_invalid,registry_no_matchorregistry_lookup_failedsays why. Only when the identifier was the request's sole description of the vehicle does a lookup timeout or outage fail it, withservice: "vehicle_registry"and no charge. The lookup is included in the request's credit. See VIN and registration plate. - Scopes, limits and billing. Normalization and the lookups need the
vehicles:readscope and share the vehicle rate limit (60 requests per minute by default); normalization neededvaluations:writebefore. Existing keys must be edited or reissued to getvehicles: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 withsynthetic: trueand asynthetic_examplenote. Request logs show lookups with thesucceededstatus.
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/accounthas a complete response schema with field descriptions in the OpenAPI document. The catalogue and account reference tables are generated from it. X-Valuation-Idheader. Valuation results fromPOST /v1/valuationsandGET /v1/valuations/{id}carry theval_…ID inX-Valuation-Id, the same value as the body'srequest_id.X-Request-Idstays the HTTP request ID on every response. See response headers.- Country availability. Each entry of
GET /v1/catalogue/countrieshasavailability:generalfor markets enabled for every new workspace,on_requestfor markets AutoUncle enables on request (currently Belgium). See markets. country_required. A valuation request with a missing ornullcountryreturns400 country_required, pointing at/country, instead of400 invalid_request.- MCP rate limits.
get_accountandget_valuationcount against the valuation rate limit like their REST equivalents and returnrate_limitedwithretry_afterandisError: truewhen it is reached. missing_mileagewording. A recorded refusal now has the samedetailandfixsteps as the error reference.- Flags. The ten
vehicle.flagswith an effect are documented keys in the contract. Other flag names give aflags_not_recognizedwarning, and a market-specific flag sent for another market givesflags_not_applicable. Unknown flags are still accepted. See 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 and a production checklist.
- API reference pages for valuations, the catalogue and the account, generated from the OpenAPI contract, with every request and response field, examples and errors per endpoint.
- Every error code with its recovery steps, generated from the error catalogue. Error
typeURLs 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.
- An expanded agent 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_limitedfor your workspace,503 engine_busyfor a market or the platform. Both are retryable with the same idempotency key. See rate & concurrency limits. - Problems gain an optional
retry_afterfield (seconds), which equals the RESTRetry-Afterheader and is the only retry delay over MCP.rate_limitednow 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 themodelthat 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) andattributions(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. - Identity levels and
inputs_used/inferreditems gain abasis:observed,extracted,catalogueorassumed. - Values interpreted by AI are no longer hinted as
imputed; their improvement hint has reasonai_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. Setoptions.allow_mileage_estimation: trueto 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: falseand, for dependency failures,serviceandreason. - Scorer timeout, outage and invalid response are distinguished as 504, 503 and 502.
- Failed and refused MCP tool results are flagged with
isError: trueand 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.