API overview

The REST API is a small JSON API over HTTPS. This page covers the conventions every endpoint shares; the endpoint pages list each field, example and error. The OpenAPI 3.1 contract (JSON) is the canonical, machine-readable description, and the field tables in this reference are generated from it.

#Endpoints

The same operations are available to agents as MCP tools; see the tool reference. APIs at a glance groups them by service.

#Base URL

https://data-services.autouncle.com

All endpoints are under /v1. Use HTTPS; there is no separate sandbox host. A test key (au_test_…) gives you simulated results on the same URL.

#Authentication

Send your API key as a Bearer token on every request:

Authorization: Bearer au_test_...

X-Api-Key: au_test_... is also accepted, but prefer Authorization. Keys belong to a workspace, are either test or live, and carry scopes. See authentication & keys.

#Requests

• JSON bodies. POST /v1/valuations requires Content-Type: application/json and a JSON object of at most 1 MB. Any other content type returns 400 invalid_request.
• Strict schemas. Unknown fields are rejected with 400 invalid_request, and each problem is listed in errors[] with a JSON Pointer to the field. This catches typos such as milage before they cost you precision.
• Omit unknowns. Leave out what you do not know rather than sending empty strings, zeros or guesses. Absent values are reflected in precision and improvement hints.
• Query parameters are plain strings. Encode spaces as %20.
• Country codes are ISO 3166-1 alpha-2 and case-insensitive (DK or dk). See markets.

#Request headers

#Responses

• JSON. Successful responses are application/json. Every result has a notes array and an attributions array, even when they are empty. See notes and data sources.
• Vehicles. Every result that describes a vehicle returns it as vehicle, an AutoUncle Vehicle Schema (AVS) 0.3 vehicle document, with how it was identified beside it in identification. Unknown values are left out, never null. Post the vehicle back unchanged as a later request's vehicle. See the Vehicle object.
• Errors before a valuation is recorded are application/problem+json Problem documents with a stable code.
• Recorded outcomes. A valuation that is refused or fails is recorded and returned as the normal valuation envelope with status and a nested error, using the error's HTTP status (for example 422 or 504).
• New fields may appear. Ignore fields you do not know; they are added without a new version. Do not rely on field order.

#Response headers

#Status codes

Every code, its meaning and how to recover is listed under errors & retries.

#Limits

See rate & concurrency limits. Contact sales if you need more.

#Versioning

The API is versioned in the path (/v1). The contract version (currently 0.9.0) is in the OpenAPI document (info.version) and in the MCP server's serverInfo.version.

Beta: expect frequent changes until 1.0. While the contract version is below 1.0, fields, endpoints, error codes, MCP tools and behaviour may change often, and some changes may break existing integrations. Every change is announced in the changelog, with breaking changes marked. From 1.0, changes within /v1 will be additive only.

Build clients that ignore fields, error codes, warning codes and enum values they do not recognise, and match on codes rather than messages. Pin the contract version you tested against and check the changelog before you upgrade.

#Client libraries

There are no official SDKs yet. The API is small enough to call with any HTTP client, and the examples in these docs show curl, Ruby (net/http), Python (requests) and JavaScript (fetch). You can also generate a client from the OpenAPI contract.