Getting started

Versioning

Last updated: October 2026

A request names the contract version it was built against in the Cardog-Version header and gets that version's shape for 12 months after the next one lands.

Your integration keeps answering the way it did when you built it. A request names the contract version it expects, and the API returns that version's shape, even after a newer version changes it.

The API serves 2 dated versions: 2026-10-21, 2026-10-26. The latest is 2026-10-26.

The header

A version is a date, YYYY-MM-DD. It travels in one request header and nowhere else:

curl "https://api.cardog.app/v2/vin/2T3R1RFV7MW180266" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26"

No header returns the oldest version still served, so an integration that never sends the header is never broken by a new version. It moves forward only when that version reaches its sunset. Send the header to get a newer shape.
A served date returns that date's shape.
Your key never selects a version. Rotating a key never changes an answer, and two services on one key can each ask for their own version.

Every /v2 response says what it served:

header	means
`Cardog-Version`	the version this response was shaped to
`Cardog-Latest-Version`	the newest version the API serves

When the two differ, a newer version exists. The changelog says what changed and why.

The SDKs pin for you

@cardog/api and the cardog Python package send Cardog-Version on every /v2 request. The value is PINNED_API_VERSION, the version the SDK release was built against. Upgrading the SDK is how you move to a newer version, and the response types match the version it pins.

import { CardogClient, PINNED_API_VERSION } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });
await client.v2.vin.getByVin("2T3R1RFV7MW180266");
client.lastVersion; // { requested, latest } from the response headers

To speak another version on purpose, while you migrate, set apiVersion (api_version= in Python). The types then describe the pinned version only, so validate what you read.

How long a version is served

A version is served for 12 months after the next version lands. A response pinned to a version that has been superseded says so in two more headers:

header	means
`Deprecation`	when the newer version landed, as `@` and Unix seconds
`Sunset`	the first day this version is no longer served

with a Link header pointing at the migration guide for the newer version, https://cardog.app/docs/migrations/<date>.

Errors

status	code	when
`400`	`invalid_request`	the header is not a date, or names a version the API does not serve. `hint` lists the served versions
`409`	`version_sunset`	the version is past its window. `hint` names a served version and links the migration guide

A version request is checked before anything is metered, so neither error costs credits.

What counts as a new version

A new version is cut only for a change that would break a working integration: a field removed, renamed or retyped, or a value that changes meaning. Adding a field, an operation or an error code is not a new version, so dispatch on the codes you know and ignore fields you do not (see Conventions).

v1

v1 is not dated. It is deprecated as of 2026-10-09, stops answering on 2027-12-31, and says so on every response in the same Deprecation, Sunset and Link headers. See the v1 overview.

Was this helpful?