# Examples

All examples read the key from `AUTOUNCLE_API_KEY`. More examples in every language: https://data-services.autouncle.com/docs/quickstart

## Check the key

```bash
curl https://data-services.autouncle.com/v1/account \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY"
```

```json
{
  "object": "account",
  "organization": { "id": "org_99ef3a8e2984f38e0b27c543", "name": "Docs Check Motors" },
  "key": { "id": "key_8ac1e502811e8e39937d1b21", "mode": "test", "scopes": ["valuations:write", "valuations:read", "catalogue:read", "account:read"] },
  "credits_remaining": 0,
  "allowed_countries": ["DK", "SE", "DE", "IT", "ES", "AT", "PT", "PL", "FI", "RO", "CH", "GB", "NL", "FR"],
  "rate_limit_per_minute": 60,
  "notes": [],
  "attributions": []
}
```

`allowed_countries` lists the markets this key can value, as the ISO codes you send in `country` (`DK`, `GB`, ...): the workspace's markets narrowed by the key's own restriction. When neither restricts the markets it lists every market; it is empty only when the key's markets and the workspace's do not overlap.

## Value from structured attributes

```bash
curl https://data-services.autouncle.com/v1/valuations \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-4711-2026-10-26" \
  -d '{"country":"DK","vehicle":{"make":"Volkswagen","model":"Golf","model_year":2020,"mileage":{"value":60000,"unit":"km"}}}'
```

Shortened test-mode result:

```json
{
  "request_id": "val_05f96b492a25a0ef9eb7aa99218a43be",
  "status": "valued",
  "mode": "test",
  "country": "DK",
  "vehicle": {
    "avs": { "version": "0.3", "kind": "vehicle" },
    "identity": {
      "brand": { "name": "VW", "ids": [{ "scheme": "autouncle", "value": "b-0957579dc5bca6de229d2f32" }] },
      "model": { "name": "Golf VII", "ids": [{ "scheme": "autouncle", "value": "cm-88dbede1978bc412872a6e1c" }] }
    },
    "vehicle": { "registration": { "country": "DK", "modelYear": 2020 }, "odometer": { "km": 60000 } }
  },
  "identification": {
    "status": "ambiguous",
    "level": "model",
    "candidates": { "generation": [{ "id": "mg-43ed101760c6bc4c4c2e44bd", "name": "Golf VII (5-door, facelift 2017)", "from_year": 2017, "to_year": 2021 }] },
    "fields": { "/identity/body": { "basis": "catalogue", "source": "catalogue_match", "status": "ambiguous", "candidate_count": 2 } }
  },
  "valuation": { "price": 102673, "currency": "DKK", "price_basis": "dealer_retail", "intervals": [{ "coverage": 0.8, "low": 82138, "high": 123208, "method": "synthetic" }] },
  "precision": { "grade": "indicative", "summary": "Synthetic sandbox result. Not a market valuation." },
  "warnings": [{ "code": "generation_ambiguous", "message": "More than one generation fits the supplied information. Select its catalogue ID for greater precision." }],
  "improve_precision": [{ "field": "vehicle.catalogue.drivetrain_id", "reason": "drivetrain_unresolved", "expected_impact": "high" }],
  "notes": [{ "code": "synthetic_result", "category": "limitation" }],
  "usage": { "billable": false, "credits_used": 0, "idempotent_replay": false, "mode": "test" }
}
```

## Value a pinned vehicle with an asking price

```json
{
  "country": "DK",
  "vehicle": { "catalogue": { "drivetrain_id": "dv-947a3199394a5a4b41cb2869" }, "model_year": 2021, "mileage": { "value": 45000, "unit": "km" } },
  "pricing": { "price_basis": "dealer_retail", "asking_price": 180000 }
}
```

The result's `vehicle` identifies brand, model and generation from the drivetrain (`source: catalogue_derived` in `identification.fields`) and adds `price_ratings.asking_price_rating` (1 to 5), `asking_price_label` and `stable_within_80pct_interval`.

## Other markets

```json
{ "country": "SE", "vehicle": { "make": "Volvo", "model": "XC60", "model_year": 2019, "mileage": { "value": 9000, "unit": "mil" } }, "pricing": { "price_basis": "private_sale" } }
```

Result currency `SEK`. In GB send miles (`"unit": "mi"`); the result is in `GBP`.

## Refusal: missing mileage

Request without `vehicle.mileage` returns HTTP 422, free:

```json
{
  "request_id": "val_ff744d44049c52dd6cb9d22b13e45636",
  "status": "refused",
  "error": {
    "code": "missing_mileage",
    "status": 422,
    "errors": [{ "pointer": "/vehicle/mileage", "message": "Actual mileage or explicit baseline permission is required." }],
    "fix": ["Supply vehicle.mileage with its value and unit.", "If a fixed baseline assumption is acceptable, set options.allow_mileage_estimation to true. Strict resolution still requires actual mileage."],
    "retryable": false,
    "billable": false
  },
  "notes": [],
  "attributions": []
}
```

With `"options": {"allow_mileage_estimation": true}` the result uses 96,000 km, adds the `km_imputed` warning and a hint with reason `imputed`, and is capped at low precision.

## Validation error

```json
{
  "type": "https://data-services.autouncle.com/docs/errors#invalid_request",
  "status": 400,
  "code": "invalid_request",
  "errors": [
    { "pointer": "/vehicle/mileage/value", "message": "Invalid number value." }
  ],
  "retryable": false,
  "billable": false
}
```

Content type `application/problem+json`. No valuation is recorded.

## Replay and conflict

Sending the same `Idempotency-Key` and the same body again returns the recorded result with `usage.idempotent_replay: true` and `credits_used: 0`. Key order in the JSON does not matter. Sending the same key with a different body returns `409 idempotency_conflict`.

## MCP tool call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "valuate_car",
    "arguments": {
      "country": "DK",
      "vehicle": { "make": "Volkswagen", "model": "Golf", "model_year": 2020, "mileage": { "value": 60000, "unit": "km" } },
      "idempotency_key": "first-valuation-001"
    }
  }
}
```

POST it to `https://data-services.autouncle.com/mcp` with `Authorization: Bearer $AUTOUNCLE_API_KEY` and `Accept: application/json, text/event-stream`.