SDKs

Two client libraries cover the whole v2 surface. Both are generated from the same OpenAPI contract the API validates against, so their types and methods cannot drift from the server. They are siblings, not translations: the same groups, the same errors, the same version pin.

First call

Free text enters once, through entities.resolve. Everything after that takes refs.

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

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const { best } = await client.v2.entities.resolve("2021 Civic");
// best.ref === "model-year:honda/civic/2021"

const identity = await client.v2.vin.getByVin("2T3R1RFV7MW180266");
const recalls = await client.v2.recalls.vin("2T3R1RFV7MW180266");

Python also ships AsyncCardog, which mirrors the whole surface with await.

Errors

Every non-2xx v2 response throws (APIErrorV2 in TypeScript, CardogAPIError in Python) with the full error envelope: code to branch on, hint for what to do next, docsUrl / docs_url, the offending refs, and nearest-ref suggestions. Suggestions are advisory and never applied for you.

import { APIErrorV2 } from "@cardog/api";

try {
  await client.v2.listings.search({ filters: { makes: ["make:teslla"] } });
} catch (err) {
  if (err instanceof APIErrorV2) {
    err.code; // "unknown_entity_refs"
    err.suggestions; // nearest real refs
  }
}

Credits

Both clients keep the last set of credit headers parsed, errors included: client.lastCredits in TypeScript, client.last_credits in Python. Each carries the call's rate, the remaining balance, the allowance, when it resets, and which pool paid. The rate card itself is a free call, client.v2.pricing(). See Credits.

Versions

Both clients send the contract version they were built against on every /v2 request, so upgrading the package is how you move to a newer API version. client.lastVersion reads the version a response was shaped to and the newest one served. See Versioning.

Refs offline

@cardog/entities is the ref grammar on its own: validate, build and type refs without a key or a network call.