# 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.

| Language | Package | Install |
|----------|---------|---------|
| TypeScript | [`@cardog/api`](https://www.npmjs.com/package/@cardog/api) | `npm install @cardog/api` |
| Python | [`cardog`](https://pypi.org/project/cardog/) | `pip install cardog` |

## First call

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

```typescript
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
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

result = client.v2.entities.resolve("2021 Civic")
ref = result.best.ref  # "model-year:honda/civic/2021"

identity = client.v2.vin.get_by_vin("2T3R1RFV7MW180266")
recalls = 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](https://cardog.app/docs/errors):
`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.

```typescript
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
`reset`s, and which pool paid. The rate card itself is a free call,
`client.v2.pricing()`. See [Credits](https://cardog.app/docs/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](https://cardog.app/docs/versioning).

## Refs offline

[`@cardog/entities`](https://cardog.app/docs/ref-grammar) is the ref grammar on its own:
validate, build and type refs without a key or a network call.

---

Previous: [Platform](https://cardog.app/docs/reference/platform.md) (API reference)
Next: [Ref grammar](https://cardog.app/docs/ref-grammar.md) (SDKs & MCP)