diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4f795ef..dd81d1a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,5 +17,6 @@ jobs: node-version: 22 cache: pnpm - run: pnpm install --frozen-lockfile + - run: pnpm format:check - run: pnpm typecheck - run: pnpm test diff --git a/.gitignore b/.gitignore index 91f4cb8..32ce250 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ dist/ # Local agent / tool artifacts CLAUDE.md +.claude/ node-compile-cache/ update-check/ playwright_chromiumdev_profile-*/ diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..ae818ea --- /dev/null +++ b/.prettierignore @@ -0,0 +1,5 @@ +dist/ +docs/ +plans/ +pnpm-lock.yaml +src/docs/data.ts diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c881fb3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +# @auto.dev/sdk + +SDK, MCP server and CLI over the auto.dev API. One client (`src/core/client.ts`), one endpoint table (`src/core/endpoints.ts`) that the SDK, the MCP tools and the CLI all read; an endpoint's `description` is the MCP tool description and the CLI help line. + +## Types + +- `src/core/types.generated.ts` is written by `pnpm generate` from `https://api.auto.dev/openapi`. Never edit it; change the converter in `scripts/openapi-to-ts.ts`. +- That spec documents one 200 per route. Anything the API answers besides that (the `/build` 207, `missing[]`) is hand-kept in `src/core/types.build.ts`, against the published contract in the docs.auto.dev repo, `src/v2.openapi.json`. + +## Checks and release + +- `pnpm format:check && pnpm typecheck && pnpm test` is CI. `pnpm test` also typechecks `test/**/*.test.ts`, so `expectTypeOf` assertions count. +- `pnpm release` bumps, tags, pushes and publishes. It runs `prepublishOnly` (docs + build) by itself. Needs `npm login` as a package owner. diff --git a/README.md b/README.md index ee92002..23d61fe 100644 --- a/README.md +++ b/README.md @@ -68,10 +68,10 @@ Settings are stored in `~/.auto-dev/config.json`. Auto.dev exposes its full vehicle data API as native [Model Context Protocol](https://modelcontextprotocol.io) tools. Two paths — pick one: -| Path | Best for | Install | -|------|----------|---------| -| **Remote** — `https://mcp.auto.dev/mcp` | Hosted clients (Claude Desktop, ChatGPT), zero setup | None — just add the URL | -| **Local stdio** — this SDK | CLI users, low-latency, offline-friendly | `npm i -g @auto.dev/sdk` | +| Path | Best for | Install | +| --------------------------------------- | ---------------------------------------------------- | ------------------------ | +| **Remote** — `https://mcp.auto.dev/mcp` | Hosted clients (Claude Desktop, ChatGPT), zero setup | None — just add the URL | +| **Local stdio** — this SDK | CLI users, low-latency, offline-friendly | `npm i -g @auto.dev/sdk` | Both expose the same tools. Remote authenticates via OAuth (one click). Stdio uses `auto login` or `AUTODEV_API_KEY`. @@ -88,6 +88,7 @@ Auto-configures Claude Code, Claude Desktop, and Cursor with the stdio MCP serve #### Claude Code **Remote:** + ```bash claude mcp add -s user -t http auto-dev https://mcp.auto.dev/mcp ``` @@ -95,6 +96,7 @@ claude mcp add -s user -t http auto-dev https://mcp.auto.dev/mcp Then run `/mcp` and select **Authenticate** for `auto-dev`. **Stdio:** + ```bash npx @auto.dev/sdk mcp install ``` @@ -161,23 +163,23 @@ Requires VS Code 1.99+ with Copilot Agent mode. ### Available MCP Tools -| Tool | Description | Plan | -|------|-------------|------| -| `auto_decode` | Decode a VIN | Free | -| `auto_photos` | Vehicle photos | Free | -| `auto_listings` | Search listings with filters | Free | -| `auto_specs` | Vehicle specifications | Growth | -| `auto_build` | OEM build data | Growth | -| `auto_recalls` | Safety recalls | Growth | -| `auto_payments` | Payment calculations | Growth | -| `auto_apr` | Interest rates | Growth | -| `auto_tco` | Total cost of ownership | Growth | -| `auto_open_recalls` | Open/unresolved recalls | Scale | -| `auto_plate` | License plate to VIN | Scale | -| `auto_taxes` | Taxes and fees | Scale | -| `auto_docs` | Search bundled API documentation | — | -| `auto_config_set` | Set a config value (e.g. `raw: true`) | — | -| `auto_config_get` | Get a config value or list all settings | — | +| Tool | Description | Plan | +| ------------------- | --------------------------------------- | ------ | +| `auto_decode` | Decode a VIN | Free | +| `auto_photos` | Vehicle photos | Free | +| `auto_listings` | Search listings with filters | Free | +| `auto_specs` | Vehicle specifications | Growth | +| `auto_build` | OEM build data | Growth | +| `auto_recalls` | Safety recalls | Growth | +| `auto_payments` | Payment calculations | Growth | +| `auto_apr` | Interest rates | Growth | +| `auto_tco` | Total cost of ownership | Growth | +| `auto_open_recalls` | Open/unresolved recalls | Scale | +| `auto_plate` | License plate to VIN | Scale | +| `auto_taxes` | Taxes and fees | Scale | +| `auto_docs` | Search bundled API documentation | — | +| `auto_config_set` | Set a config value (e.g. `raw: true`) | — | +| `auto_config_get` | Get a config value or list all settings | — | ## SDK @@ -231,37 +233,37 @@ All methods return: ### SDK Methods -| Method | Tier | Description | -|--------|------|-------------| -| `decode(vin)` | Free | Decode VIN — make, model, year, trim | -| `photos(vin)` | Free | Vehicle photos | -| `listings(filters?)` | Free | Search listings with filters | -| `specs(vin)` | Growth | Detailed vehicle specifications | -| `build(vin)` | Growth | OEM build and trim data; a 207 partial answer (`build: null`, `vehicle`, `catalog`, `reason`) when no record builds the VIN, see `isPartialBuild` | -| `recalls(vin)` | Growth | Safety recalls | -| `payments(vin, opts?)` | Growth | Monthly payment calculations | -| `apr(vin, opts?)` | Growth | Interest rates by credit profile | -| `tco(vin, opts?)` | Growth | Total cost of ownership | -| `openRecalls(vin)` | Scale | Open/unresolved recalls | -| `plate(state, plate)` | Scale | License plate to VIN | -| `taxes(vin, opts?)` | Scale | Taxes and fees | -| `usage()` | — | Account usage statistics | +| Method | Tier | Description | +| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `decode(vin)` | Free | Decode VIN — make, model, year, trim | +| `photos(vin)` | Free | Vehicle photos | +| `listings(filters?)` | Free | Search listings with filters | +| `specs(vin)` | Growth | Detailed vehicle specifications | +| `build(vin)` | Growth | OEM build and trim data; a 207 partial answer (`build: null`, `vehicle`, `catalog`, `reason`) when no record builds the VIN, see `isPartialBuild` | +| `recalls(vin)` | Growth | Safety recalls | +| `payments(vin, opts?)` | Growth | Monthly payment calculations | +| `apr(vin, opts?)` | Growth | Interest rates by credit profile | +| `tco(vin, opts?)` | Growth | Total cost of ownership | +| `openRecalls(vin)` | Scale | Open/unresolved recalls | +| `plate(state, plate)` | Scale | License plate to VIN | +| `taxes(vin, opts?)` | Scale | Taxes and fees | +| `usage()` | — | Account usage statistics | ### Subpath Exports ```typescript -import { AutoDev } from '@auto.dev/sdk' // SDK client -import { createMcpServer } from '@auto.dev/sdk/mcp' // MCP server -import { AutoDevClient } from '@auto.dev/sdk/core' // low-level client +import { AutoDev } from '@auto.dev/sdk' // SDK client +import { createMcpServer } from '@auto.dev/sdk/mcp' // MCP server +import { AutoDevClient } from '@auto.dev/sdk/core' // low-level client ``` ## Plans & Pricing -| Plan | Monthly | Endpoints | -|------|---------|-----------| -| **Free** | $0, no card | Decode, Listings, Photos | +| Plan | Monthly | Endpoints | +| ---------- | ------------------- | ------------------------------------------- | +| **Free** | $0, no card | Decode, Listings, Photos | | **Growth** | $299/mo + data fees | + Specs, Build, Recalls, Payments, APR, TCO | -| **Scale** | $599/mo + data fees | + Open Recalls, Plate-to-VIN, Taxes & Fees | +| **Scale** | $599/mo + data fees | + Open Recalls, Plate-to-VIN, Taxes & Fees | Free includes 1,000 API calls/month as a hard cap — requests stop at the limit and there are no data fees. Growth and Scale bill all API calls. See [auto.dev/pricing](https://auto.dev/pricing) diff --git a/package.json b/package.json index 290d0d2..af7bed6 100644 --- a/package.json +++ b/package.json @@ -37,6 +37,7 @@ "typecheck": "tsc --noEmit", "format": "prettier --write .", "format:check": "prettier --check .", + "release": "pnpm version patch && git push --follow-tags && pnpm publish --access public", "prepublishOnly": "pnpm build:docs && pnpm build:docs-data && pnpm build" }, "keywords": [ diff --git a/scripts/build-docs.ts b/scripts/build-docs.ts index 25581cf..2af6e60 100644 --- a/scripts/build-docs.ts +++ b/scripts/build-docs.ts @@ -138,7 +138,10 @@ function convertMdxToMarkdown(content: string): string { // Single line version md = md.replace(//g, '\n```$2\n$1\n```\n') // Multi-line version - md = md.replace(//g, '\n```$2\n$1\n```\n') + md = md.replace( + //g, + '\n```$2\n$1\n```\n', + ) // Remove any remaining JSX self-closing tags md = md.replace(/<[A-Z]\w+[^>]*\/>/g, '') diff --git a/src/auth/oauth.ts b/src/auth/oauth.ts index f042009..35b3d10 100644 --- a/src/auth/oauth.ts +++ b/src/auth/oauth.ts @@ -28,7 +28,7 @@ export async function getValidToken(clientType: ClientType = 'cli'): Promise { +export async function saveTokenData(data: { + access_token: string + refresh_token?: string + expires_in?: number +}): Promise { await storage.setTokenData({ accessToken: data.access_token, refreshToken: data.refresh_token, diff --git a/src/auth/resolve.ts b/src/auth/resolve.ts index 53c348e..2eea9fe 100644 --- a/src/auth/resolve.ts +++ b/src/auth/resolve.ts @@ -3,10 +3,7 @@ import { AutoDevError } from '../errors' import type { ClientType } from '../core/types' export async function resolveAuth(options?: { apiKey?: string; clientType?: ClientType }): Promise { - const apiKey = - options?.apiKey ?? - process.env.AUTODEV_API_KEY ?? - await getValidToken(options?.clientType ?? 'cli') + const apiKey = options?.apiKey ?? process.env.AUTODEV_API_KEY ?? (await getValidToken(options?.clientType ?? 'cli')) if (!apiKey) { throw new AutoDevError(401, 'UNAUTHORIZED', 'No API key found', 'Set AUTODEV_API_KEY or run: auto login') diff --git a/src/cli/auth.ts b/src/cli/auth.ts index 6f5a65a..7702e50 100644 --- a/src/cli/auth.ts +++ b/src/cli/auth.ts @@ -2,7 +2,14 @@ import { exec } from 'node:child_process' import { platform } from 'node:os' import { Command } from 'commander' import { DEFAULT_AUTH_CONFIG } from '../auth/config' -import { authorizeDevice, clearCredentials, getValidToken, pollForTokens, saveApiKey, saveTokenData } from '../auth/oauth' +import { + authorizeDevice, + clearCredentials, + getValidToken, + pollForTokens, + saveApiKey, + saveTokenData, +} from '../auth/oauth' import { buildAuthHeaders } from '../core/user-agent' import { brand, formatError, formatSuccess, header, hint, kv, value } from './colors' import { createSpinner } from './spinner' @@ -30,7 +37,8 @@ export function buildLoginCommand(): Command { const deviceCode = await authorizeDevice(DEFAULT_AUTH_CONFIG.clientId, CLI_HEADERS) deviceSpinner.stop() - const verifyUrl = deviceCode.verification_uri_complete || `${deviceCode.verification_uri}?user_code=${deviceCode.user_code}` + const verifyUrl = + deviceCode.verification_uri_complete || `${deviceCode.verification_uri}?user_code=${deviceCode.user_code}` console.log(`\n${brand('auto.dev')} ${hint('authentication')}`) console.log(`\nOpening browser to: ${value(verifyUrl)}`) console.log(`If it doesn't open, visit: ${value(deviceCode.verification_uri)}`) @@ -38,7 +46,13 @@ export function buildLoginCommand(): Command { openBrowser(verifyUrl) console.log(hint('Waiting for authorization...')) - const token = await pollForTokens(DEFAULT_AUTH_CONFIG.clientId, deviceCode.device_code, deviceCode.interval, deviceCode.expires_in, CLI_HEADERS) + const token = await pollForTokens( + DEFAULT_AUTH_CONFIG.clientId, + deviceCode.device_code, + deviceCode.interval, + deviceCode.expires_in, + CLI_HEADERS, + ) await saveTokenData(token) console.log(formatSuccess('Login successful!')) @@ -52,41 +66,37 @@ export function buildLoginCommand(): Command { } export function buildLogoutCommand(): Command { - const cmd = new Command('logout') - .description('Log out and clear stored credentials') - .action(async () => { - await clearCredentials('cli') - console.log(formatSuccess('Logged out. Credentials cleared.')) - }) + const cmd = new Command('logout').description('Log out and clear stored credentials').action(async () => { + await clearCredentials('cli') + console.log(formatSuccess('Logged out. Credentials cleared.')) + }) return cmd } export function buildWhoamiCommand(): Command { - const cmd = new Command('whoami') - .description('Show current user and active org') - .action(async () => { - const token = await getValidToken('cli') - if (!token) { - console.log(formatError('Not logged in', 'Run: auto login')) - return - } - const { getUser } = await import('../auth/oauth') - const whoamiSpinner = createSpinner() - const { user } = await getUser(token, CLI_HEADERS) - whoamiSpinner.stop() - if (user) { - console.log(`\n${header('auto.dev')}`) - console.log() - console.log(kv('Email', user.email ?? 'unknown', 2)) - console.log(kv('Name ', user.name ?? 'unknown', 2)) - console.log(kv('ID ', user.id, 2)) - if (user.organizationId) console.log(kv('Org ', user.organizationId, 2)) - console.log() - } else { - console.log(hint('Authenticated (could not fetch user info)')) - } - }) + const cmd = new Command('whoami').description('Show current user and active org').action(async () => { + const token = await getValidToken('cli') + if (!token) { + console.log(formatError('Not logged in', 'Run: auto login')) + return + } + const { getUser } = await import('../auth/oauth') + const whoamiSpinner = createSpinner() + const { user } = await getUser(token, CLI_HEADERS) + whoamiSpinner.stop() + if (user) { + console.log(`\n${header('auto.dev')}`) + console.log() + console.log(kv('Email', user.email ?? 'unknown', 2)) + console.log(kv('Name ', user.name ?? 'unknown', 2)) + console.log(kv('ID ', user.id, 2)) + if (user.organizationId) console.log(kv('Org ', user.organizationId, 2)) + console.log() + } else { + console.log(hint('Authenticated (could not fetch user info)')) + } + }) return cmd } diff --git a/src/cli/colors.ts b/src/cli/colors.ts index b3e37fe..c63cd0c 100644 --- a/src/cli/colors.ts +++ b/src/cli/colors.ts @@ -10,26 +10,26 @@ function colorsEnabled(): boolean { } function ansi(code: string) { - return (text: string) => colorsEnabled() ? `${code}${text}\x1b[0m` : text + return (text: string) => (colorsEnabled() ? `${code}${text}\x1b[0m` : text) } // Core palette — matches auto.dev website -export const purple = ansi('\x1b[35m') // brand accent -export const boldPurple = ansi('\x1b[1;35m') // headers, command names -export const cyan = ansi('\x1b[36m') // values, data -export const boldCyan = ansi('\x1b[1;36m') // important values -export const dim = ansi('\x1b[2m') // secondary info -export const bold = ansi('\x1b[1m') // emphasis -export const green = ansi('\x1b[32m') // success -export const boldGreen = ansi('\x1b[1;32m') // success headers -export const limeGreen = ansi('\x1b[33m') // links/URLs -export const brown = ansi('\x1b[38;5;180m') // string values -export const yellowNum = ansi('\x1b[92m') // numbers and booleans (bright green) -export const red = ansi('\x1b[31m') // errors -export const boldRed = ansi('\x1b[1;31m') // error headers -export const yellow = ansi('\x1b[33m') // warnings -export const white = ansi('\x1b[37m') // neutral -export const boldWhite = ansi('\x1b[1;37m') // labels +export const purple = ansi('\x1b[35m') // brand accent +export const boldPurple = ansi('\x1b[1;35m') // headers, command names +export const cyan = ansi('\x1b[36m') // values, data +export const boldCyan = ansi('\x1b[1;36m') // important values +export const dim = ansi('\x1b[2m') // secondary info +export const bold = ansi('\x1b[1m') // emphasis +export const green = ansi('\x1b[32m') // success +export const boldGreen = ansi('\x1b[1;32m') // success headers +export const limeGreen = ansi('\x1b[33m') // links/URLs +export const brown = ansi('\x1b[38;5;180m') // string values +export const yellowNum = ansi('\x1b[92m') // numbers and booleans (bright green) +export const red = ansi('\x1b[31m') // errors +export const boldRed = ansi('\x1b[1;31m') // error headers +export const yellow = ansi('\x1b[33m') // warnings +export const white = ansi('\x1b[37m') // neutral +export const boldWhite = ansi('\x1b[1;37m') // labels // Semantic aliases export const brand = boldPurple diff --git a/src/cli/commands.ts b/src/cli/commands.ts index 9fd98ce..e13093b 100644 --- a/src/cli/commands.ts +++ b/src/cli/commands.ts @@ -2,6 +2,7 @@ import type { Command } from 'commander' import { ENDPOINTS } from '../core/endpoints' import { type CommandDef, makeCommand } from './factory' +// prettier-ignore const commands: CommandDef[] = [ // Simple VIN commands { name: 'decode', description: 'Decode a VIN — returns make, model, year, trim, engine, drivetrain' }, diff --git a/src/cli/config.ts b/src/cli/config.ts index 5f42876..8cfab2b 100644 --- a/src/cli/config.ts +++ b/src/cli/config.ts @@ -3,8 +3,7 @@ import { loadConfig, saveConfig } from '../core/config' import { brand, formatSuccess, hint, label, value } from './colors' export function buildConfigCommand(): Command { - const config = new Command('config') - .description('Manage auto.dev CLI configuration') + const config = new Command('config').description('Manage auto.dev CLI configuration') config .command('set') diff --git a/src/cli/explore.ts b/src/cli/explore.ts index 06edf8b..b55f4b6 100644 --- a/src/cli/explore.ts +++ b/src/cli/explore.ts @@ -21,77 +21,246 @@ export interface ParameterDetail { required: boolean type: string description: string - apiParam?: string // real API param name if different from shorthand + apiParam?: string // real API param name if different from shorthand } const PARAM_DETAILS: Record = { decode: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], photos: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], listings: [ - { name: 'make', in: 'query', required: false, type: 'string', description: 'Vehicle manufacturer. Comma-separated for multiple', apiParam: 'vehicle.make' }, - { name: 'model', in: 'query', required: false, type: 'string', description: 'Vehicle model. Comma-separated for multiple', apiParam: 'vehicle.model' }, - { name: 'year', in: 'query', required: false, type: 'string', description: 'Year or range (2018-2020)', apiParam: 'vehicle.year' }, + { + name: 'make', + in: 'query', + required: false, + type: 'string', + description: 'Vehicle manufacturer. Comma-separated for multiple', + apiParam: 'vehicle.make', + }, + { + name: 'model', + in: 'query', + required: false, + type: 'string', + description: 'Vehicle model. Comma-separated for multiple', + apiParam: 'vehicle.model', + }, + { + name: 'year', + in: 'query', + required: false, + type: 'string', + description: 'Year or range (2018-2020)', + apiParam: 'vehicle.year', + }, { name: 'trim', in: 'query', required: false, type: 'string', description: 'Trim level', apiParam: 'vehicle.trim' }, - { name: 'bodyStyle', in: 'query', required: false, type: 'string', description: 'Body style (sedan, coupe, etc)', apiParam: 'vehicle.bodyStyle' }, - { name: 'price', in: 'query', required: false, type: 'string', description: 'Price range (e.g. 10000-30000)', apiParam: 'retailListing.price' }, - { name: 'miles', in: 'query', required: false, type: 'string', description: 'Mileage range (e.g. 0-50000)', apiParam: 'retailListing.miles' }, - { name: 'state', in: 'query', required: false, type: 'string', description: 'State code (e.g. CA, TX)', apiParam: 'retailListing.state' }, - { name: 'sort', in: 'query', required: false, type: 'string', description: 'Sort criteria (e.g. price:asc, year:desc)' }, + { + name: 'bodyStyle', + in: 'query', + required: false, + type: 'string', + description: 'Body style (sedan, coupe, etc)', + apiParam: 'vehicle.bodyStyle', + }, + { + name: 'price', + in: 'query', + required: false, + type: 'string', + description: 'Price range (e.g. 10000-30000)', + apiParam: 'retailListing.price', + }, + { + name: 'miles', + in: 'query', + required: false, + type: 'string', + description: 'Mileage range (e.g. 0-50000)', + apiParam: 'retailListing.miles', + }, + { + name: 'state', + in: 'query', + required: false, + type: 'string', + description: 'State code (e.g. CA, TX)', + apiParam: 'retailListing.state', + }, + { + name: 'sort', + in: 'query', + required: false, + type: 'string', + description: 'Sort criteria (e.g. price:asc, year:desc)', + }, { name: 'page', in: 'query', required: false, type: 'integer', description: 'Page number (starting from 1)' }, { name: 'limit', in: 'query', required: false, type: 'integer', description: 'Results per page (1-100)' }, ], specs: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], build: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], recalls: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], payments: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, { name: 'price', in: 'query', required: true, type: 'string', description: 'Vehicle sales price' }, - { name: 'zip', in: 'query', required: true, type: 'string', description: '5-digit ZIP code for tax/fee calculations' }, + { + name: 'zip', + in: 'query', + required: true, + type: 'string', + description: '5-digit ZIP code for tax/fee calculations', + }, { name: 'downPayment', in: 'query', required: false, type: 'number', description: 'Down payment amount' }, { name: 'loanTerm', in: 'query', required: false, type: 'number', description: 'Loan term in months' }, { name: 'docFee', in: 'query', required: false, type: 'number', description: 'Dealer documentation fee' }, { name: 'tradeIn', in: 'query', required: false, type: 'string', description: 'Trade-in vehicle value' }, ], apr: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, { name: 'year', in: 'query', required: true, type: 'number', description: 'Model year of the vehicle' }, { name: 'make', in: 'query', required: true, type: 'string', description: 'Vehicle manufacturer' }, { name: 'model', in: 'query', required: true, type: 'string', description: 'Vehicle model name' }, - { name: 'zip', in: 'query', required: true, type: 'string', description: '5-digit ZIP code for location-based rates' }, - { name: 'creditScore', in: 'query', required: true, type: 'string', description: 'Credit score for rate calculation' }, + { + name: 'zip', + in: 'query', + required: true, + type: 'string', + description: '5-digit ZIP code for location-based rates', + }, + { + name: 'creditScore', + in: 'query', + required: true, + type: 'string', + description: 'Credit score for rate calculation', + }, { name: 'vehicleAge', in: 'query', required: false, type: 'number', description: 'Age of the vehicle in years' }, { name: 'vehicleMileage', in: 'query', required: false, type: 'string', description: 'Current vehicle mileage' }, ], tco: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, - { name: 'zip', in: 'query', required: false, type: 'string', description: '5-digit ZIP code for location-based calculations' }, - { name: 'fromZip', in: 'query', required: false, type: 'string', description: '5-digit ZIP code for delivery/transport calculations' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, + { + name: 'zip', + in: 'query', + required: false, + type: 'string', + description: '5-digit ZIP code for location-based calculations', + }, + { + name: 'fromZip', + in: 'query', + required: false, + type: 'string', + description: '5-digit ZIP code for delivery/transport calculations', + }, ], openRecalls: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, ], plate: [ { name: 'state', in: 'path', required: true, type: 'string', description: '2-letter state code (e.g. CA, NY, TX)' }, - { name: 'plate', in: 'path', required: true, type: 'string', description: 'License plate number (2-8 alphanumeric characters)' }, + { + name: 'plate', + in: 'path', + required: true, + type: 'string', + description: 'License plate number (2-8 alphanumeric characters)', + }, ], taxes: [ - { name: 'vin', in: 'path', required: true, type: 'string', description: '17-character Vehicle Identification Number' }, + { + name: 'vin', + in: 'path', + required: true, + type: 'string', + description: '17-character Vehicle Identification Number', + }, { name: 'price', in: 'query', required: false, type: 'number', description: 'Vehicle price (default 25000)' }, - { name: 'zip', in: 'query', required: false, type: 'string', description: 'ZIP code for tax jurisdiction (default 94020)' }, + { + name: 'zip', + in: 'query', + required: false, + type: 'string', + description: 'ZIP code for tax jurisdiction (default 94020)', + }, { name: 'docFee', in: 'query', required: false, type: 'number', description: 'Documentation fee (default 200)' }, - { name: 'tradeIn', in: 'query', required: false, type: 'number', description: 'Trade-in value to deduct (default 0)' }, + { + name: 'tradeIn', + in: 'query', + required: false, + type: 'number', + description: 'Trade-in value to deduct (default 0)', + }, { name: 'rate', in: 'query', required: false, type: 'number', description: 'Interest rate (default 9.99)' }, - { name: 'downPayment', in: 'query', required: false, type: 'number', description: 'Down payment amount (default 0)' }, + { + name: 'downPayment', + in: 'query', + required: false, + type: 'number', + description: 'Down payment amount (default 0)', + }, { name: 'months', in: 'query', required: false, type: 'integer', description: 'Loan term in months (default 72)' }, ], usage: [], diff --git a/src/cli/factory.ts b/src/cli/factory.ts index 6449420..cbf38ac 100644 --- a/src/cli/factory.ts +++ b/src/cli/factory.ts @@ -130,15 +130,17 @@ export function makeCommand(def: CommandDef): Command { // ── Helpers (moved from commands.ts) ─────────────────────────────────── export function colorizeJson(json: string): string { - return json - .replace(/"([^"]+)":/g, (_, key) => `${value(`"${key}"`)}:`) - .replace(/: "(https?:\/\/[^"]+)"/g, (_, url) => `: "${limeGreen(url)}"`) - // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — prevents re-colorizing ANSI-escaped strings - .replace(/: "([^"\x1b]*)"/g, (_, str) => `: ${brown(`"${str}"`)}`) - .replace(/: (-?\d+\.?\d*)(,?\n)/g, (_, num, end) => `: ${yellowNum(num)}${end}`) - .replace(/: (true|false)(,?\n)/g, (_, bool, end) => `: ${yellowNum(bool)}${end}`) - .replace(/: (null)(,?\n)/g, (_, nul, end) => `: ${yellowNum(nul)}${end}`) - .replace(/^(\s+)(-?\d+\.?\d*)(,?\n)/gm, (_, indent, num, end) => `${indent}${yellowNum(num)}${end}`) + return ( + json + .replace(/"([^"]+)":/g, (_, key) => `${value(`"${key}"`)}:`) + .replace(/: "(https?:\/\/[^"]+)"/g, (_, url) => `: "${limeGreen(url)}"`) + // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — prevents re-colorizing ANSI-escaped strings + .replace(/: "([^"\x1b]*)"/g, (_, str) => `: ${brown(`"${str}"`)}`) + .replace(/: (-?\d+\.?\d*)(,?\n)/g, (_, num, end) => `: ${yellowNum(num)}${end}`) + .replace(/: (true|false)(,?\n)/g, (_, bool, end) => `: ${yellowNum(bool)}${end}`) + .replace(/: (null)(,?\n)/g, (_, nul, end) => `: ${yellowNum(nul)}${end}`) + .replace(/^(\s+)(-?\d+\.?\d*)(,?\n)/gm, (_, indent, num, end) => `${indent}${yellowNum(num)}${end}`) + ) } export function formatOutput(data: unknown, format: string): string { @@ -153,17 +155,11 @@ export function formatOutput(data: unknown, format: string): string { const hasNested = Object.values(data[0] as object).some((v) => typeof v === 'object' && v !== null) if (hasNested) return colorizeJson(JSON.stringify(data, null, 2)) const keys = Object.keys(data[0] as object) - const allRows = (data as Record[]).map((row) => - keys.map((k) => String(row[k] ?? '')), - ) - const colWidths = keys.map((k, i) => - Math.max(k.length, ...allRows.map((r) => r[i]!.length)), - ) + const allRows = (data as Record[]).map((row) => keys.map((k) => String(row[k] ?? ''))) + const colWidths = keys.map((k, i) => Math.max(k.length, ...allRows.map((r) => r[i]!.length))) const pad = (s: string, w: number) => s + ' '.repeat(Math.max(0, w - s.length)) const header = keys.map((k, i) => label(pad(k, colWidths[i]!))).join(' ') - const body = allRows.map((row) => - row.map((val, i) => pad(val, colWidths[i]!)).join(' '), - ) + const body = allRows.map((row) => row.map((val, i) => pad(val, colWidths[i]!)).join(' ')) return [header, ...body].join('\n') } return colorizeJson(JSON.stringify(data, null, 2)) diff --git a/src/cli/index.ts b/src/cli/index.ts index e56922d..5866237 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -30,7 +30,6 @@ if (process.argv.includes('--mcp')) { }) })() } else { - program.addCommand(buildLoginCommand()) program.addCommand(buildLogoutCommand()) program.addCommand(buildWhoamiCommand()) @@ -39,14 +38,24 @@ if (process.argv.includes('--mcp')) { program.addCommand(buildConfigCommand()) const orgs = new Command('orgs').description('Manage organizations') - orgs.command('list').description('List your organizations').action(() => { - console.log('Organization listing requires authentication. Run: auto login') - }) - orgs.command('switch').argument('', 'Organization slug').description('Switch active organization').action(async (slug) => { - const token = await getValidToken('cli') - if (!token) { console.error('Not logged in. Run: auto login'); process.exit(1) } - console.log(`Switched to organization: ${slug}`) - }) + orgs + .command('list') + .description('List your organizations') + .action(() => { + console.log('Organization listing requires authentication. Run: auto login') + }) + orgs + .command('switch') + .argument('', 'Organization slug') + .description('Switch active organization') + .action(async (slug) => { + const token = await getValidToken('cli') + if (!token) { + console.error('Not logged in. Run: auto login') + process.exit(1) + } + console.log(`Switched to organization: ${slug}`) + }) program.addCommand(orgs) const docs = new Command('docs') @@ -61,7 +70,20 @@ if (process.argv.includes('--mcp')) { } console.log(`\n${brand('auto.dev')} ${hint('Documentation')}\n`) // Show in same order as explore endpoints - const order = ['decode', 'photos', 'listings', 'specs', 'build', 'recalls', 'payments', 'apr', 'tco', 'openRecalls', 'plate', 'taxes'] + const order = [ + 'decode', + 'photos', + 'listings', + 'specs', + 'build', + 'recalls', + 'payments', + 'apr', + 'tco', + 'openRecalls', + 'plate', + 'taxes', + ] const aliases = getAliases() for (const shortcut of order) { const docName = aliases[shortcut] ?? shortcut @@ -85,7 +107,7 @@ if (process.argv.includes('--mcp')) { console.log(formatError(`No docs found for "${query}"`)) const available = listDocs() if (available.length > 0) { - console.log(` ${hint('Available:')} ${available.map(n => value(n)).join(hint(', '))}`) + console.log(` ${hint('Available:')} ${available.map((n) => value(n)).join(hint(', '))}`) } return } @@ -93,7 +115,12 @@ if (process.argv.includes('--mcp')) { console.log(`\n${brand('auto.dev')} ${hint('docs')} ${value(results[0]!.name)}\n`) console.log(results[0]!.content) if (results.length > 1) { - console.log(`\n${hint('Also related:')} ${results.slice(1).map((r) => value(r.name)).join(hint(', '))}`) + console.log( + `\n${hint('Also related:')} ${results + .slice(1) + .map((r) => value(r.name)) + .join(hint(', '))}`, + ) } }) diff --git a/src/cli/mcp-install.ts b/src/cli/mcp-install.ts index e198915..befcc37 100644 --- a/src/cli/mcp-install.ts +++ b/src/cli/mcp-install.ts @@ -51,7 +51,17 @@ const MCP_CLIENTS: McpClient[] = [ }, { name: 'Cline', - configPath: join(homedir(), 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json'), + configPath: join( + homedir(), + 'Library', + 'Application Support', + 'Code', + 'User', + 'globalStorage', + 'saoudrizwan.claude-dev', + 'settings', + 'cline_mcp_settings.json', + ), key: 'mcpServers', serverConfig: { ...BASE_SERVER_CONFIG }, }, diff --git a/src/core/client.ts b/src/core/client.ts index f70cb56..95db16c 100644 --- a/src/core/client.ts +++ b/src/core/client.ts @@ -27,7 +27,12 @@ export class AutoDevClient { constructor(options?: AutoDevClientOptions) { const apiKey = options?.apiKey ?? process.env.AUTODEV_API_KEY - if (!apiKey) throw new AutoDevError(401, 'UNAUTHORIZED', 'No API key provided. Pass apiKey in options or set AUTODEV_API_KEY env variable.') + if (!apiKey) + throw new AutoDevError( + 401, + 'UNAUTHORIZED', + 'No API key provided. Pass apiKey in options or set AUTODEV_API_KEY env variable.', + ) this.apiKeyOrResolver = apiKey this.org = options?.org this.baseUrl = options?.baseUrl ?? 'https://api.auto.dev' @@ -64,9 +69,7 @@ export class AutoDevClient { // Most endpoints return { error: string }; the auth middleware returns { error: { message } } const errorBody = body as { error?: string | { message?: string }; suggestion?: string; upgradeLink?: string } const message = - typeof errorBody.error === 'string' - ? errorBody.error - : (errorBody.error?.message ?? response.statusText) + typeof errorBody.error === 'string' ? errorBody.error : (errorBody.error?.message ?? response.statusText) const code = this.statusToCode(response.status) const suggestion = this.getSuggestion(response.status, definition.tier, errorBody.upgradeLink) throw new AutoDevError(response.status, code, message, suggestion) @@ -79,7 +82,7 @@ export class AutoDevClient { consumer: this.raw, config: config.raw, }) - const data = isRaw ? rawData : stripMetadata(rawData as Record) as T + const data = isRaw ? rawData : (stripMetadata(rawData as Record) as T) return { data, diff --git a/src/core/strip.ts b/src/core/strip.ts index 7168950..04f15cb 100644 --- a/src/core/strip.ts +++ b/src/core/strip.ts @@ -15,7 +15,7 @@ export function resolveRaw(options?: RawOptions): boolean { export function stripMetadata(response: Record): unknown { const stripped = Object.fromEntries( - Object.entries(response).filter(([key]) => !(METADATA_KEYS as readonly string[]).includes(key)) + Object.entries(response).filter(([key]) => !(METADATA_KEYS as readonly string[]).includes(key)), ) const keys = Object.keys(stripped) if (keys.length === 1) return stripped[keys[0]!] diff --git a/src/core/types.ts b/src/core/types.ts index 782a9ff..12c2c1a 100644 --- a/src/core/types.ts +++ b/src/core/types.ts @@ -18,4 +18,12 @@ export interface AutoDevClientOptions { } // Re-export generated param types under SDK-friendly names -export type { AprVinParams as AprOptions, ListingsVinParams as ListingsFilters, PaymentsVinParams as PaymentOptions, RecallsVinParams as RecallsOptions, TaxesVinParams as TaxOptions, TcoVinParams as TcoOptions, TransportVinParams as TransportOptions } from './types.generated' +export type { + AprVinParams as AprOptions, + ListingsVinParams as ListingsFilters, + PaymentsVinParams as PaymentOptions, + RecallsVinParams as RecallsOptions, + TaxesVinParams as TaxOptions, + TcoVinParams as TcoOptions, + TransportVinParams as TransportOptions, +} from './types.generated' diff --git a/src/docs/data.ts b/src/docs/data.ts index a9565e8..078e389 100644 --- a/src/docs/data.ts +++ b/src/docs/data.ts @@ -3,16 +3,16 @@ // Run `pnpm build:docs-data` to regenerate. export const DOCS_DATA: Record = { - "interest-rates": "Get current interest rates for auto loans, leases, and other financing options. Retrieve personalized rates based on vehicle details, credit score, location, and loan terms.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/apr/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `year` | number | Model year of the vehicle | |\n| `make` | string | Vehicle manufacturer | |\n| `model` | string | Vehicle model name | |\n| `zip` | string | 5-digit ZIP code for location-based rates | |\n| `creditScore` | string | Credit score for rate calculation | |\n| `vehicleAge` | number | Age of the vehicle in years | |\n| `vehicleMileage` | string | Current vehicle mileage | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch(\n 'https://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000',\n {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n },\n)\n\nconst rates = await response.json()\nconsole.log(rates.apr)\n```\n\n```python tab=\"Python\"\n\nurl = 'https://api.auto.dev/apr/1C4HJXEN5MW592818'\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nparams = {\n 'year': 2021,\n 'make': 'Jeep',\n 'model': 'Wrangler',\n 'zip': '37129',\n 'creditScore': '720',\n 'vehicleAge': 3,\n 'vehicleMileage': '36000'\n}\n\nresponse = requests.get(url, headers=headers, params=params)\nrates = response.json()\nprint(rates['apr'])\n```\n\n```php tab=\"PHP\"\n 2021,\n 'make' => 'Jeep',\n 'model' => 'Wrangler',\n 'zip' => '37129',\n 'creditScore' => '720',\n 'vehicleAge' => 3,\n 'vehicleMileage' => '36000'\n]);\n\n$url = \"https://api.auto.dev/apr/{$vin}?{$queryParams}\";\n\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, $url);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n]);\n\n$response = curl_exec($ch);\n$rates = json_decode($response, true);\necho json_encode($rates['apr']);\ncurl_close($ch);\n?>\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle` | object | Vehicle information used for rate calculation | |\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model | |\n| `zip` | string | ZIP code used for location-based rates | |\n| `creditScore` | string | Credit score used for rate calculation | |\n| `vehicleAge` | number | Age of vehicle in years | |\n| `vehicleMileage` | string | Vehicle mileage | |\n| `apr` | object | Interest rates by loan term in months | |\n| `apr.36` | number | 36-month loan APR percentage | |\n| `apr.48` | number | 48-month loan APR percentage | |\n| `apr.60` | number | 60-month loan APR percentage | |\n| `apr.72` | number | 72-month loan APR percentage | |\n| `apr.84` | number | 84-month loan APR percentage | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1C4HJXEN5MW592818\",\n \"year\": 2021,\n \"make\": \"Jeep\",\n \"model\": \"Wrangler\"\n },\n \"zip\": \"37129\",\n \"creditScore\": \"720\",\n \"vehicleAge\": 3,\n \"vehicleMileage\": \"36000\",\n \"apr\": {\n \"36\": 7.644,\n \"48\": 7.644,\n \"60\": 7.524,\n \"72\": 7.663,\n \"84\": 8.263\n }\n}\n```\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/apr/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/apr/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "oem-build-data": "Retrieve complete vehicle build information based on the VIN, including exact trim details, drivetrain, engine specifications, interior/exterior colors, factory options, and MSRP data. This comprehensive API provides the most detailed vehicle information available from OEM build records.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/build/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/build/1FTFW3LDXRFB40317\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/build/1FTFW3LDXRFB40317\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/build/1FTFW3LDXRFB40317', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst buildData = await response.json()\nconsole.log(buildData.build)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/build/1FTFW3LDXRFB40317',\n headers=headers\n)\n\nbuild_data = response.json()\nprint(build_data['build'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/build/1FTFW3LDXRFB40317',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$buildData = json_decode($response, true);\nprint_r($buildData['build']);\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.vin` | string | Vehicle Identification Number | |\n| `build.year` | number | Model year | |\n| `build.make` | string | Vehicle manufacturer | |\n| `build.model` | string | Vehicle model name | |\n| `build.trim` | string | Complete trim designation | |\n| `build.series` | string | Vehicle series or sub-model | |\n| `build.style` | string | Body style designation (e.g., \"4D Crossover\") | |\n| `build.drivetrain` | string | Drivetrain configuration (e.g., \"RWD\", \"AWD\") | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.engine` | string | Complete engine specification with displacement, configuration, and horsepower | |\n| `build.transmission` | string | Transmission type and configuration | |\n| `build.confidence` | number | Data accuracy confidence score (0-1) | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.interiorColor` | object | Interior color name and hex code mapping | |\n| `build.exteriorColor` | object | Exterior color name and hex code mapping | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.options` | object | Factory option codes mapped to descriptions | |\n| `build.optionsMsrp` | number | Total MSRP value of factory options in USD | |\n\n## Example Response\n\n```json\n{\n \"build\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2024,\n \"make\": \"Ford\",\n \"model\": \"F-150\",\n \"trim\": \"XLT\",\n \"series\": \"XLT\",\n \"style\": \"4D SuperCrew\",\n \"drivetrain\": \"4WD\",\n \"engine\": \"3.5L V-6 gasoline direct injection, DOHC, twin turbocharged, regular unleaded, engine with 400HP\",\n \"transmission\": \"10-speed automatic\",\n \"confidence\": 0.99,\n \"interiorColor\": {\n \"Black Onyx\": \"#1C1C1C\"\n },\n \"exteriorColor\": {\n \"Iconic Silver Metallic\": \"#C0C0C0\"\n },\n \"options\": {\n \"53A\": \"XLT Mid Equipment Group\",\n \"99N\": \"Iconic Silver Metallic\",\n \"FX4\": \"FX4 Off-Road Package\",\n \"86M\": \"Trailer Tow Package\"\n },\n \"optionsMsrp\": 4295\n }\n}\n```\n\n## Use Cases\n\n- **Appraisal Services**: Factor in factory options and original colors for accurate vehicle valuations\n- **Insurance Underwriting**: Use confidence scores and build specifications for risk assessment\n- **Parts & Service**: Match exact factory option codes for correct parts ordering\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/build/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/build/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n### VIN Decode Failed\n\n```json\n{\n \"status\": 400,\n \"error\": \"Unable to decode vehicle information from VIN\",\n \"code\": \"VIN_DECODE_FAILED\",\n \"path\": \"/build/1FMDE0AP0SLA20048\",\n \"requestId\": \"976d19586b52612e\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "open-recalls": "Get currently active and unresolved vehicle recall information from the National Highway Traffic Safety Administration (NHTSA) database. This API filters out completed, closed, or resolved recalls to show only those requiring immediate attention or repair action.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/openrecalls/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/openrecalls/1FMUK7DHXSGA27345\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve open recalls for | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst openRecalls = await response.json()\nconsole.log(`Found ${openRecalls.data.length} open recalls requiring attention`)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345',\n headers=headers\n)\n\nopen_recalls = response.json()\nprint(f\"Found {len(open_recalls['data'])} open recalls requiring attention\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$openRecalls = json_decode($response, true);\necho \"Found \" . count($openRecalls['data']) . \" open recalls requiring attention\\n\";\n?>\n```\n\n## Response Structure\n\n### Main Response\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `data` | array | Array of open recall records for the specified vehicle | |\n\n### Open Recall Record Fields\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `manufacturer` | string | Vehicle manufacturer who issued the recall | |\n| `nhtsaCampaignNumber` | string | Unique NHTSA recall campaign identifier | |\n| `parkIt` | boolean | Critical safety flag - vehicle should not be driven until repaired | |\n| `parkOutSide` | boolean | Critical safety flag - vehicle should be parked away from structures | |\n| `overTheAirUpdate` | boolean | Whether recall can be resolved via software update without dealer visit | |\n| `reportReceivedDate` | string | Date NHTSA received the recall report (DD/MM/YYYY format) | |\n| `component` | string | Vehicle component or system affected by the recall | |\n| `summary` | string | Detailed description of the recall issue and affected vehicles | |\n| `consequence` | string | Potential safety consequences if the recall is not addressed | |\n| `remedy` | string | Manufacturer instructions for resolving the recall issue | |\n| `notes` | string | Additional notes and contact information for vehicle owners | |\n| `recallStatus` | string | Current status of the recall (Open, In Progress, Remedy Available) | |\n| `expectedRemediationDate` | string | Expected date when remedy will be available (if applicable) | |\n| `modelYear` | string | Vehicle model year | |\n| `make` | string | Vehicle make (manufacturer) | |\n| `model` | string | Vehicle model name | |\n\n## Example Response\n\n### Vehicle with Open Recalls\n\n```json\n{\n \"data\": [\n {\n \"manufacturer\": \"Ford Motor Company\",\n \"nhtsaCampaignNumber\": \"25V239000\",\n \"parkIt\": false,\n \"parkOutSide\": false,\n \"overTheAirUpdate\": false,\n \"reportReceivedDate\": \"11/04/2025\",\n \"component\": \"POWER TRAIN:AUTOMATIC TRANSMISSION:CONTROL MODULE:SOFTWARE\",\n \"summary\": \"Ford Motor Company (Ford) is recalling certain 2025 Explorer vehicles. The powertrain control module (PCM) may reset while driving, which can damage the park system or cause an engine stall.\",\n \"consequence\": \"A damaged park system can result in a vehicle rollaway when the vehicle is placed in park without the parking brake applied. An engine stall while driving can result in a sudden loss of drive power. Either of these scenarios can increase the risk of a crash.\",\n \"remedy\": \"Dealers will update the powertrain control module software, free of charge. Owner notification letters were mailed June 6, 2025. Owners may contact Ford customer service at 1-866-436-7332. Ford's number for this recall is 25S35.\",\n \"notes\": \"Owners may also contact the National Highway Traffic Safety Administration Vehicle Safety Hotline at 888-327-4236 (TTY 888-275-9171) or go to nhtsa.gov.\",\n \"modelYear\": \"2025\",\n \"make\": \"FORD\",\n \"model\": \"EXPLORER\"\n }\n ]\n}\n```\n\n### Vehicle with No Open Recalls\n\nWhen a valid VIN has no open recalls, the API returns an empty array:\n\n```json\n{\n \"data\": []\n}\n```\n\n**Note**: This means all recalls have been completed, resolved, or the vehicle has no recall history.\n\n## Critical Safety Classifications\n\n### Immediate Action Required\n\n- **Park It** (`parkIt: true`) - **DO NOT DRIVE** - Vehicle poses immediate safety risk and should not be operated until repaired\n- **Park Outside** (`parkOutSide: true`) - **FIRE/EXPLOSION RISK** - Vehicle should be parked away from structures, garages, and other vehicles\n\n### Resolution Methods\n\n- **Over-the-Air Update** (`overTheAirUpdate: true`) - Can be resolved via software update without dealership visit\n- **Dealer Service Required** - Physical repair or part replacement needed at authorized service center\n\n### Recall Status Types\n\n- **Open** - Recall announced, remedy not yet available\n- **Remedy Available** - Fix is available, customer action required\n- **In Progress** - Customer has scheduled or begun remedy process\n\n## Use Cases\n\n- **Pre-Purchase Inspections**: Identify vehicles requiring immediate attention before sale\n- **Safety Alert Systems**: Notify owners of critical recalls requiring immediate action\n- **Fleet Management**: Prioritize vehicles needing urgent recall remediation\n- **Insurance Risk Assessment**: Evaluate vehicles with unresolved safety issues\n\n## Differences from Vehicle Recalls API\n\n| Feature | Vehicle Recalls API | Open Recalls API |\n| ----------------- | ------------------------ | ----------------------------------- |\n| **Scope** | All historical recalls | Only active/unresolved recalls |\n| **Use Case** | Complete recall history | Immediate action items |\n| **Status Filter** | All statuses | Open, In Progress, Remedy Available |\n| **Response Size** | Larger (historical data) | Smaller (active only) |\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/openrecalls/1GYKPD\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/openrecalls/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "plate-to-vin": "Quickly decode any US license plate to get the VIN, year, make, model, and comprehensive vehicle information. This powerful API connects license plate data to detailed vehicle records across all 50 states.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/plate/{plateState}/{plateNumber}?state={state}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/plate/CA/ABC123\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `plate` | string | US license plate number to lookup | |\n| `state` | string | 2-letter state code where the plate is registered (e.g., CA, NY, TX) | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/plate/CA/ABC123\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/plate/CA/ABC123', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst plateData = await response.json()\nconsole.log(plateData.vehicle)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/plate/CA/ABC123',\n headers=headers\n)\n\nplate_data = response.json()\nprint(plate_data['vehicle'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/plate/CA/ABC123',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$plateData = json_decode($response, true);\nprint_r($plateData['vehicle']);\n?>\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | Complete 17-character Vehicle Identification Number | |\n| `year` | number | Model year of the vehicle | |\n| `make` | string | Vehicle manufacturer name | |\n| `model` | string | Vehicle model name | |\n| `trim` | string | Complete trim designation | |\n| `drivetrain` | string | Vehicle drivetrain configuration | |\n| `engine` | string | Engine specification | |\n| `transmission` | string | Transmission type | |\n| `isDefault` | boolean | Whether this is the default configuration for the VIN | |\n\n## Example Response\n\n```json\n{\n \"vin\": \"1N4BL4BV3LC205823\",\n \"year\": 2020,\n \"make\": \"Nissan\",\n \"model\": \"Altima\",\n \"trim\": \"2.5 S Sedan 4D\",\n \"drivetrain\": \"FWD\",\n \"engine\": \"4-Cyl, 2.5 Liter\",\n \"transmission\": \"Automatic, Xtronic CVT\",\n \"isDefault\": true\n}\n```\n\n## State Coverage\n\nThe Plate-to-VIN API supports license plate lookups across all 50 US states with varying coverage levels by region.\n\n### Supported Plate Formats\n\n- **Standard plates**: ABC123, 123ABC, AB1234\n- **Vanity plates**: Custom personalized plates\n- **Commercial plates**: Truck, taxi, and fleet vehicles\n- **Special formats**: Plates with hyphens (AB-123) are automatically handled\n\n## Error Responses\n\n### Invalid License Plate\n\n```json\n{\n \"status\": 400,\n \"error\": \"License plate must be 2-8 alphanumeric characters\",\n \"code\": \"INVALID_PLATE_FORMAT\",\n \"path\": \"/plate/CA/ABC12345XYZ\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### Invalid State Code\n\n```json\n{\n \"status\": 400,\n \"error\": \"State must be a valid 2-letter US state code (e.g., CA, NY, TX)\",\n \"code\": \"INVALID_STATE_CODE\",\n \"path\": \"/plate/XX/ABC123\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n### No Data Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"License plate found but no vehicle data available\",\n \"code\": \"NO_DATA_FOUND\",\n \"path\": \"/plate/CA/ABC123\",\n \"requestId\": \"d4e5f6g7h8i9j0k1\"\n}\n```\n\n### Plate Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle found for the provided license plate\",\n \"code\": \"PLATE_NOT_FOUND\",\n \"path\": \"/plate/CA/XYZ999\",\n \"requestId\": \"c3d4e5f6g7h8i9j0\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "specifications": "Get detailed vehicle specifications including engine details, features, measurements, colors, options, and complete technical data for any vehicle by VIN. Access comprehensive spec data organized by category for easy integration.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/specs/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/specs/1FTFW3LDXRFB40317\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve specifications for | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/specs/1FTFW3LDXRFB40317\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/specs/1FTFW3LDXRFB40317', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst specs = await response.json()\nconsole.log(specs.specs)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/specs/1FTFW3LDXRFB40317',\n headers=headers\n)\n\nspecs = response.json()\nprint(specs['specs'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/specs/1FTFW3LDXRFB40317',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$specs = json_decode($response, true);\nprint_r($specs['specs']);\n?>\n```\n\n## Response Structure\n\n### Vehicle Information\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.manufacturer` | string | Full manufacturer name | |\n\n### Basic Specifications\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.name` | string | Complete trim and specification name | |\n| `specs.totalSeating` | number | Total seating capacity | |\n| `specs.price.baseMsrp` | number | Manufacturer Suggested Retail Price | |\n| `specs.price.baseInvoice` | number | Dealer invoice price | |\n\n### Engine Specifications\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.engine.baseEngineSize` | string | Engine displacement (e.g., \"4.0 L\") | |\n| `specs.features.engine.cylinders` | string | Engine configuration (e.g., \"flat 6\") | |\n| `specs.features.engine.horsepower` | string | Engine horsepower rating with RPM | |\n| `specs.features.engine.torque` | string | Engine torque rating with RPM | |\n| `specs.features.engine.baseEngineType` | string | Fuel type (e.g., \"gas\") | |\n| `specs.features.engine.valves` | string | Number of valves | |\n| `specs.features.engine.camType` | string | Camshaft configuration | |\n| `specs.features.engine.valveTiming` | string | Valve timing type | |\n| `specs.features.engine.directInjection` | boolean | Direct injection availability | |\n\n### Measurements & Dimensions\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.measurements.length` | string | Overall vehicle length | |\n| `specs.features.measurements.height` | string | Overall vehicle height | |\n| `specs.features.measurements.wheelbase` | string | Wheelbase measurement | |\n| `specs.features.measurements.curbWeight` | string | Vehicle curb weight | |\n| `specs.features.measurements.grossWeight` | string | Gross vehicle weight | |\n| `specs.features.measurements.maximumPayload` | string | Maximum payload capacity | |\n| `specs.features.measurements.overallWidthWithMirrors` | string | Total width including mirrors | |\n| `specs.features.measurements.overallWidthWithoutMirrors` | string | Width excluding mirrors | |\n| `specs.features.measurements.manufacturer060MphAccelerationTime` | string | Manufacturer-rated 0-60 mph acceleration time | |\n| `specs.features.measurements.turningCircle` | string | Turning circle diameter | |\n| `specs.features.measurements.maximumCargoCapacity` | string | Maximum cargo capacity | |\n| `specs.features.measurements.countryOfFinalAssembly` | string | Country where vehicle was assembled | |\n\n### Fuel Economy\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.fuel.fuelType` | string | Required fuel type | |\n| `specs.features.fuel.epaCombinedMpg` | string | EPA combined MPG rating | |\n| `highwayMpg` | string | EPA city/highway MPG ratings | |\n| `specs.features.fuel.fuelTankCapacity` | string | Fuel tank capacity | |\n\n### Drive Train\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.driveTrain.driveType` | string | Drive wheel configuration (e.g., \"rear wheel drive\") | |\n| `specs.features.driveTrain.transmission` | string | Transmission type and configuration | |\n| `specs.features.driveTrain.rearLimitedSlipDifferential` | boolean | Rear limited slip differential availability | |\n| `specs.features.driveTrain.rearLockingDifferential` | boolean | Rear locking differential availability | |\n\n### Color Options\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.color.exterior` | array | Array of available exterior colors | |\n| `.name` | string | Color name | |\n| `.rgb` | string | RGB color values | |\n| `specs.color.interior` | array | Array of available interior colors | |\n| `.name` | string | Interior color/material name | |\n| `.rgb` | string | RGB color values | |\n\n### Additional Response Fields\n\n### Warranty Information\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.warranty.basic` | string | Basic warranty coverage | |\n| `specs.features.warranty.drivetrain` | string | Drivetrain warranty coverage | |\n| `specs.features.warranty.rust` | string | Corrosion/rust warranty | |\n| `specs.features.warranty.roadsideAssistance` | string | Roadside assistance coverage | |\n| `specs.features.warranty.freeMaintenance` | string | Free maintenance period | |\n\n### Ordered Features\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.orderedFeatures` | array | Array of feature categories with organized data | |\n| `.category` | string | Feature category name (e.g., \"Engine\", \"Safety\") | |\n| `.categoryGroup` | string | High-level grouping (e.g., \"Mechanical\", \"Interior\") | |\n| `.features` | object | Object containing category-specific features | |\n\n### Style Attributes\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.styleAttributes.electric` | boolean | Whether vehicle is electric | |\n| `specs.styleAttributes.pluginElectric` | boolean | Whether vehicle is plug-in electric | |\n| `specs.styleAttributes.truck` | boolean | Whether vehicle is classified as a truck | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2019,\n \"make\": \"Porsche\",\n \"model\": \"911\",\n \"manufacturer\": \"Dr Ing HCF Porsch Ag\"\n },\n \"specs\": {\n \"name\": \"GT3 RS 2dr Coupe (4.0L 6cyl 7AM)\",\n \"price\": {\n \"baseMsrp\": 187500,\n \"baseInvoice\": 168750\n },\n \"totalSeating\": 2,\n \"color\": {\n \"exterior\": [\n {\n \"name\": \"Lizard Green\",\n \"rgb\": \"87,178,44\"\n },\n {\n \"name\": \"Miami Blue\",\n \"rgb\": \"3,161,192\"\n },\n {\n \"name\": \"Racing Yellow\",\n \"rgb\": \"229,200,38\"\n },\n {\n \"name\": \"Guards Red\",\n \"rgb\": \"175,26,28\"\n }\n ],\n \"interior\": [\n {\n \"name\": \"Black, leather/sueded microfiber\",\n \"rgb\": \"0,0,0\"\n },\n {\n \"name\": \"Black/Lizard Green, leather/sueded microfiber\",\n \"rgb\": \"0,0,0\"\n }\n ]\n },\n \"features\": {\n \"engine\": {\n \"torque\": \"346 lb-ft @ 6000 rpm\",\n \"baseEngineSize\": \"4.0 L\",\n \"horsepower\": \"520 hp @ 8250 rpm\",\n \"valves\": \"24\",\n \"baseEngineType\": \"gas\",\n \"directInjection\": true,\n \"valveTiming\": \"Variable\",\n \"cylinders\": \"flat 6\",\n \"camType\": \"Double overhead cam (DOHC)\"\n },\n \"fuel\": {\n \"epaCombinedMpg\": \"16 MPG\",\n \"epaCity/highwayMpg\": \"15/19 MPG\",\n \"rangeInMiles (city/hwy)\": \"253.5/321.1 mi.\",\n \"fuelTankCapacity\": \"16.9 gal.\",\n \"fuelType\": \"premium unleaded (required)\"\n },\n \"measurements\": {\n \"maximumCargoCapacity\": \"4.4 cu.ft.\",\n \"countryOfFinalAssembly\": \"Germany\",\n \"wheelbase\": \"96.6 in.\",\n \"curbWeight\": \"3153 lbs.\",\n \"grossWeight\": \"3953 lbs.\",\n \"cargoCapacity,AllSeatsInPlace\": \"4.4 cu.ft.\",\n \"maximumPayload\": \"800 lbs.\",\n \"overallWidthWithMirrors\": \"77.9 in.\",\n \"length\": \"179.4 in.\",\n \"manufacturer060MphAccelerationTime\": \"3.0 seconds\",\n \"turningCircle\": \"36.4 ft.\",\n \"height\": \"51.1 in.\",\n \"overallWidthWithoutMirrors\": \"74.0 in.\"\n },\n \"driveTrain\": {\n \"driveType\": \"rear wheel drive\",\n \"rearLockingDifferential\": true,\n \"rearLimitedSlipDifferential\": true,\n \"transmission\": \"7-speed automated manual\"\n },\n \"warranty\": {\n \"basic\": \"4 yr./ 50000 mi.\",\n \"drivetrain\": \"4 yr./ 50000 mi.\",\n \"freeMaintenance\": \"1 yr./ 10000 mi.\",\n \"rust\": \"12 yr./ unlimited mi.\",\n \"roadsideAssistance\": \"4 yr./ 50000 mi.\"\n },\n \"safety\": {\n \"4WheelAbs\": true,\n \"daytimeRunningLights\": true,\n \"engineImmobilizer\": true,\n \"postCollisionSafetySystem\": true,\n \"frontHeadAirbags\": true,\n \"dualFrontSideMountedAirbags\": true,\n \"passengerAirbagOccupantSensingDeactivation\": true,\n \"stabilityControl\": true,\n \"tirePressureMonitoring\": true,\n \"tractionControl\": true\n },\n \"frontseats\": {\n \"heightAdjustablePassengerSeat\": true,\n \"heightAdjustableDriverSeat\": true,\n \"sportFrontSeats\": true,\n \"2WayPowerPassengerSeat\": true,\n \"leather/suededMicrofiber\": true,\n \"2WayPowerDriverSeat\": true\n }\n },\n \"orderedFeatures\": [\n {\n \"category\": \"Fuel\",\n \"categoryGroup\": \"Mechanical\",\n \"features\": {\n \"fuelType\": \"Premium unleaded (required)\",\n \"epaCity/highwayMpg\": \"15/19 MPG\",\n \"epaCombinedMpg\": \"16 MPG\",\n \"rangeInMiles (city/hwy)\": \"253.5/321.1 mi.\",\n \"fuelTankCapacity\": \"16.9 gal.\"\n }\n },\n {\n \"category\": \"Engine\",\n \"categoryGroup\": \"Mechanical\",\n \"features\": {\n \"baseEngineSize\": \"4.0 L\",\n \"cylinders\": \"Flat 6\",\n \"baseEngineType\": \"Gas\",\n \"horsepower\": \"520 hp @ 8250 rpm\",\n \"torque\": \"346 lb-ft @ 6000 rpm\",\n \"valves\": \"24\",\n \"camType\": \"Double overhead cam (DOHC)\",\n \"valveTiming\": \"Variable\",\n \"directInjection\": true\n }\n }\n ],\n \"typeCategories\": {\n \"performancesports\": {\n \"id\": 10,\n \"name\": \"Performance/Sports\"\n },\n \"coupe\": {\n \"id\": 2,\n \"name\": \"Coupe\"\n },\n \"luxury\": {\n \"id\": 8,\n \"name\": \"Luxury\"\n }\n },\n \"styleAttributes\": {\n \"electric\": false,\n \"pluginElectric\": false,\n \"truck\": false\n }\n }\n}\n```\n\n## Feature Categories\n\nThe API returns comprehensive feature data organized into the following categories through the `orderedFeatures` array:\n\n### Mechanical Systems\n\n**Engine**:\n\n- Engine displacement, configuration, and type\n- Horsepower and torque ratings with RPM\n- Valve configuration and timing systems\n- Direct injection and fuel delivery\n\n**Drive Train**:\n\n- Transmission type and gear count\n- Drive wheel configuration (FWD, RWD, AWD, 4WD)\n- Differential options (limited slip, locking)\n- Transfer case specifications\n\n**Fuel**:\n\n- Fuel type requirements (regular, premium, etc.)\n- EPA city, highway, and combined MPG ratings\n- Fuel tank capacity and estimated range\n- Fuel system specifications\n\n**Suspension**:\n\n- Front and rear suspension types\n- Stabilizer bar configurations\n- Performance suspension options\n\n### Exterior Features\n\n**Measurements**:\n\n- Overall dimensions (length, width, height)\n- Wheelbase and track measurements\n- Weight specifications (curb, gross, payload)\n- Performance metrics (0-60 acceleration)\n- Cargo and storage capacities\n\n**Tires and Wheels**:\n\n- Wheel sizes and materials\n- Tire specifications and performance ratings\n- Available wheel finishes and options\n\n**Exterior Options**:\n\n- Lighting packages and LED systems\n- Body kit and aerodynamic elements\n- Mirror and trim options\n- Paint and finish selections\n\n### Interior Features\n\n**Seating**:\n\n- Seating capacity and configurations\n- Seat materials and adjustability options\n- Heating, cooling, and massage features\n- Memory and power adjustments\n\n**Comfort & Convenience**:\n\n- Climate control systems (single/dual zone)\n- Infotainment and connectivity features\n- Storage compartments and cup holders\n- Power accessories and convenience features\n\n**Interior Options**:\n\n- Premium material selections\n- Color and trim combinations\n- Ambient lighting packages\n- Technology and luxury upgrades\n\n### Safety & Security\n\n**Active Safety**:\n\n- Collision avoidance and mitigation systems\n- Driver assistance technologies\n- Stability and traction control systems\n- Emergency braking and steering assist\n\n**Passive Safety**:\n\n- Airbag systems and configurations\n- Structural safety reinforcements\n- Child safety systems and LATCH\n- Security and anti-theft systems\n\n**Safety & Security Options**:\n\n- Advanced driver assistance packages\n- Security system upgrades\n- Emergency response features\n\n### Technology & Entertainment\n\n**In Car Entertainment**:\n\n- Audio system specifications and speakers\n- Infotainment display and interface\n- Smartphone integration (Apple CarPlay, Android Auto)\n- Navigation and mapping systems\n- Satellite radio and streaming services\n\n**Telematics**:\n\n- Connected services and remote access\n- Vehicle tracking and stolen vehicle assistance\n- Over-the-air update capabilities\n- Emergency and concierge services\n\n### Packages & Options\n\n**Packages**:\n\n- Manufacturer option packages\n- Performance and appearance packages\n- Luxury and convenience bundles\n- Special edition and delivery options\n\n**Mechanical Options**:\n\n- Performance upgrades and modifications\n- Suspension and handling packages\n- Brake system upgrades\n- Powertrain enhancements\n\n## Use Cases\n\n- **Vehicle Comparison Tools**: Compare detailed specifications across multiple vehicles for purchase decisions with organized feature categories\n- **Automotive Marketplaces**: Display comprehensive vehicle features and specifications in listings with proper categorization\n- **Configuration Builders**: Help customers select vehicle options and packages based on available features and categories\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be 17 characters long\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/specs/123Invalid\",\n \"requestId\": \"966d9900bef4356c-IAD\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/specs/1FTFW3LDXRFB40317\",\n \"requestId\": \"f8g7h6i5j4k3l2m1\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "taxes-fees": "Retrieve comprehensive tax and fee calculations for vehicle sales transactions. This API provides accurate, location-specific tax rates and government fees, ensuring compliance with local regulations and transparent pricing for both dealers and consumers.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/taxes/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/taxes/19UDE2F31MA000428?zip=94020&price=25000&docFee=200\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | The Vehicle Identification Number (e.g. 19UDE2F31MA000428) | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `price` | number | The vehicle price (e.g., 25000). Defaults to 25000 if not provided. | |\n| `zip` | string | The ZIP code of the location (e.g. 94020). If not provided, defaults to user zipcode or 94020. | |\n| `docFee` | number | Documentation fee (e.g., 200). Defaults to 200 if not provided. | |\n| `tradeIn` | number | Trade-in value to deduct from taxable amount (e.g., 5000). Defaults to 0 if not provided. | |\n| `rate` | number | Interest rate for financing calculations (e.g., 9.99). Defaults to 9.99 if not provided. | |\n| `downPayment` | number | Down payment amount (e.g., 5000). Defaults to 0 if not provided. | |\n| `months` | number | Loan term in months (e.g., 72). Defaults to 72 if not provided. | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/taxes/19UDE2F31MA000428?zip=94020&price=25000&docFee=200\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n```javascript tab=\"JavaScript\"\nconst vin = '19UDE2F31MA000428'\nconst params = new URLSearchParams({\n zip: '94020',\n price: '25000',\n docFee: '200',\n rate: '9.99',\n})\n\nconst response = await fetch(`https://api.auto.dev/taxes/${vin}?${params}`, {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n },\n})\n\nconst taxData = await response.json()\nconsole.log(`Total: $${taxData.totalTaxesAndFees}`)\n```\n\n```python tab=\"Python\"\n\nvin = '19UDE2F31MA000428'\nparams = {\n 'zip': '94020',\n 'price': '25000',\n 'docFee': '200',\n 'rate': '9.99'\n}\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY'\n}\n\nresponse = requests.get(\n f'https://api.auto.dev/taxes/{vin}',\n headers=headers,\n params=params\n)\n\ntax_data = response.json()\nprint(f\"Total: ${tax_data['totalTaxesAndFees']}\")\n```\n\n```php tab=\"PHP\"\n '94020',\n 'price' => '25000',\n 'docFee' => '200',\n 'rate' => '9.99'\n]);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"https://api.auto.dev/taxes/{$vin}?{$params}\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY'\n ]\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$taxData = json_decode($response, true);\necho \"Total: $\" . $taxData['totalTaxesAndFees'];\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | string | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `criteria.price` | number | Vehicle sale price used for calculations | |\n| `criteria.zip` | string | ZIP code for tax jurisdiction lookup | |\n| `criteria.docFee` | number | Documentation fee included in calculation | |\n| `criteria.tradeIn` | string | Trade-in value deducted from taxable amount | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `totalTaxesAndFees` | number | Total amount of all taxes and fees combined | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `taxes.stateSalesTax` | number | State-level sales tax amount | |\n| `taxes.countySalesTax` | number | County-level sales tax amount | |\n| `taxes.citySalesTax` | number | City-level sales tax amount | |\n| `taxes.districtSalesTax` | number | Special district sales tax amount | |\n| `taxes.combinedSalesTax` | number | Total of all sales taxes | |\n| `taxes.gasGuzzlerTax` | number | Federal gas guzzler tax (if applicable) | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `fees.titleFee` | number | Vehicle title processing fee | |\n| `fees.registrationFee` | number | Vehicle registration fee | |\n| `fees.dmvFee` | number | Standard DMV processing fee | |\n| `fees.docFee` | number | Dealer documentation fee | |\n| `fees.combinedFees` | number | Total of all government fees | |\n| `fees.dmvFees` | object | Detailed breakdown of DMV-specific fees | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"19UDE2F31MA000428\",\n \"year\": 2021,\n \"make\": \"Acura\",\n \"model\": \"ILX\"\n },\n \"criteria\": {\n \"price\": \"85000\",\n \"zip\": \"90210\",\n \"docFee\": 200,\n \"tradeIn\": 0\n },\n \"totalTaxesAndFees\": 9585.5,\n \"taxes\": {\n \"citySalesTax\": 637.5,\n \"combinedSalesTax\": 8500,\n \"countySalesTax\": 212.5,\n \"districtSalesTax\": 2550,\n \"stateSalesTax\": 5100,\n \"gasGuzzlerTax\": 0\n },\n \"fees\": {\n \"titleFee\": 23,\n \"registrationFee\": 65,\n \"dmvFee\": 797.5,\n \"combinedFees\": 1085.5,\n \"docFee\": 200,\n \"dmvFees\": {\n \"Air Quality Fee\": 6,\n \"Alternative Fuel/Technology Fee\": 3,\n \"Auto theft deterrence/DUI fee\": 2,\n \"Fingerprint ID Fee\": 1,\n \"Highway Patrol Fee\": 29,\n \"Reflectorized license plate fee\": 1,\n \"Service Authority for Freeway Emergencies fee\": 1,\n \"Smog Abatement Fee\": 12,\n \"Transfer Fee\": 15,\n \"Transportation Improvement Fee\": 175,\n \"Vehicle License Fee\": 552.5\n }\n }\n}\n```\n\n## Use Cases\n\n- **Dealership Sales Calculator**: Build accurate \"out-the-door\" pricing for customers including all taxes and fees\n- **Multi-State Comparison**: Compare total registration costs across different states for purchase optimization\n- **Financing Integration**: Calculate accurate amounts to finance including all applicable taxes and fees\n\n## Error Responses\n\n### Invalid Request\n\n```json\n{\n \"status\": 400,\n \"error\": \"Oops! Something went wrong while fetching your taxes.\",\n \"code\": \"INVALID_REQUEST\",\n \"path\": \"/taxes/1FTFW3LDXRFB40317?zip=12345\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\",\n \"suggestion\": \"Please check zip code: 12345\"\n}\n```\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/taxes/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/taxes/1FTFW3LDXRFB40317\",\n \"requestId\": \"c3d4e5f6g7h8i9j0\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "total-cost-ownership": "Calculate comprehensive Total Cost of Ownership (TCO) for any vehicle over a 5-year period. Get detailed breakdowns of all ownership costs including depreciation, fuel, maintenance, repairs, insurance, taxes, and financing.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/tco/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/tco/1FTFW3LDXRFB40317?zip=90210&milesPerYear=12000\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `zip` | string | 5-digit ZIP code for location-based calculations (insurance, taxes, fees) | Auto-detected based on user location |\n| `fromZip` | string | 5-digit ZIP code for delivery/transport calculations | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/tco/1FTFW3LDXRFB40317?zip=76548&fromZip=60695\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst vin = '1FTFW3LDXRFB40317'\nconst params = new URLSearchParams({\n zip: '76548',\n fromZip: '60695',\n})\n\nconst response = await fetch(`https://api.auto.dev/tco/${vin}?${params}`, {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst tco = await response.json()\nconsole.log(`Total 5-year cost: $${tco.tco.total.tcoPrice}`)\nconsole.log(`Average cost per mile: $${tco.tco.total.averageCostPerMile}`)\n```\n\n```python tab=\"Python\"\n\nvin = '1FTFW3LDXRFB40317'\nparams = {\n 'zip': '76548',\n 'fromZip': '60695'\n}\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(f'https://api.auto.dev/tco/{vin}', params=params, headers=headers)\ntco = response.json()\nprint(f\"Total 5-year cost: ${tco['tco']['total']['tcoPrice']}\")\n```\n\n```php tab=\"PHP\"\n '76548',\n 'fromZip' => '60695'\n]);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"https://api.auto.dev/tco/{$vin}?{$query}\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$tco = json_decode($response, true);\necho \"Total 5-year cost: $\" . $tco['tco']['total']['tcoPrice'] . \"\\n\";\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.manufacturer` | string | Full manufacturer name | |\n| `zip` | string | ZIP code used for location-based calculations | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `tco.total.federalTaxCredit` | number | Federal tax credits available (electric vehicles) | |\n| `tco.total.insurance` | number | Total insurance costs over 5 years | |\n| `tco.total.maintenance` | number | Total maintenance costs over 5 years | |\n| `tco.total.repairs` | number | Total repair costs over 5 years | |\n| `tco.total.taxesAndFees` | number | Total taxes and fees over 5 years | |\n| `tco.total.financeInterest` | number | Total financing interest over 5 years | |\n| `tco.total.depreciation` | number | Total depreciation over 5 years | |\n| `tco.total.fuel` | number | Total fuel costs over 5 years | |\n| `tco.total.tcoPrice` | number | Total cost of ownership over 5 years | |\n| `tco.total.averageCostPerMile` | number | Average cost per mile over 5 years | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `.insurance` | number | Insurance costs for the year | |\n| `.maintenance` | number | Maintenance costs for the year | |\n| `.repairs` | number | Repair costs for the year | |\n| `.taxesAndFees` | number | Taxes and fees for the year | |\n| `.financeInterest` | number | Financing interest for the year | |\n| `.depreciation` | number | Depreciation for the year | |\n| `.fuel` | number | Fuel costs for the year | |\n| `.tcoPrice` | number | Total cost for the year | |\n| `.averageCostPerMile` | number | Average cost per mile for the year | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2019,\n \"make\": \"Porsche\",\n \"model\": \"911\",\n \"manufacturer\": \"Dr Ing HCF Porsch Ag\"\n },\n \"zip\": \"90210\",\n \"tco\": {\n \"total\": {\n \"federalTaxCredit\": 0,\n \"insurance\": 12110,\n \"maintenance\": 13788,\n \"repairs\": 11874,\n \"taxesAndFees\": 12164,\n \"financeInterest\": 20657,\n \"depreciation\": 44236,\n \"fuel\": 25000,\n \"tcoPrice\": 139829,\n \"averageCostPerMile\": 1.86\n },\n \"years\": {\n \"1\": {\n \"insurance\": 2281,\n \"maintenance\": 2006,\n \"repairs\": 2038,\n \"taxesAndFees\": 9728,\n \"financeInterest\": 7077,\n \"depreciation\": 13474,\n \"fuel\": 4709,\n \"tcoPrice\": 41313,\n \"averageCostPerMile\": 1.86\n },\n \"2\": {\n \"insurance\": 2349,\n \"maintenance\": 147,\n \"repairs\": 2195,\n \"taxesAndFees\": 684,\n \"financeInterest\": 5710,\n \"depreciation\": 7566,\n \"fuel\": 4850,\n \"tcoPrice\": 23501,\n \"averageCostPerMile\": 1.86\n },\n \"3\": {\n \"insurance\": 2420,\n \"maintenance\": 6898,\n \"repairs\": 2364,\n \"taxesAndFees\": 635,\n \"financeInterest\": 4241,\n \"depreciation\": 8510,\n \"fuel\": 4996,\n \"tcoPrice\": 30064,\n \"averageCostPerMile\": 1.86\n },\n \"4\": {\n \"insurance\": 2493,\n \"maintenance\": 694,\n \"repairs\": 2543,\n \"taxesAndFees\": 579,\n \"financeInterest\": 2663,\n \"depreciation\": 6296,\n \"fuel\": 5145,\n \"tcoPrice\": 20413,\n \"averageCostPerMile\": 1.86\n },\n \"5\": {\n \"insurance\": 2567,\n \"maintenance\": 4043,\n \"repairs\": 2734,\n \"taxesAndFees\": 538,\n \"financeInterest\": 966,\n \"depreciation\": 8390,\n \"fuel\": 5300,\n \"tcoPrice\": 24538,\n \"averageCostPerMile\": 1.86\n }\n }\n }\n}\n```\n\n## Cost Component Analysis\n\nThe TCO calculation includes five main cost components:\n\n- **Depreciation** - Vehicle value loss over time (largest cost factor)\n- **Fuel Costs** - Based on EPA ratings and local fuel prices\n- **Financing Interest** - Loan interest payments over ownership period\n- **Insurance** - Annual insurance premiums based on vehicle and location\n- **Maintenance & Repairs** - Scheduled maintenance and expected repairs\n\n## Use Cases\n\n- **Vehicle Purchase Decisions**: Compare total ownership costs between different vehicles before buying\n- **Fleet Management**: Evaluate long-term costs for fleet vehicle selection and budget planning\n- **Lease vs Buy Analysis**: Calculate comprehensive costs to determine optimal vehicle acquisition strategy\n\n## Error Responses\n\n### Invalid Location\n\n```json\n{\n \"status\": 400,\n \"error\": \"Invalid ZIP code format. ZIP code must be 5 digits (e.g., 90210) or 5+4 format (e.g., 90210-1234)\",\n \"code\": \"INVALID_LOCATION\",\n \"path\": \"/tco/1GYKPDRSXSZ102995?zip=ABCDE\",\n \"requestId\": \"d4e5f6g7h8i9j0k1\"\n}\n```\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/tco/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "vehicle-listings": "Get comprehensive vehicle listings from U.S. physical & online dealers in seconds. Our Vehicle Listings API provides detailed vehicle information, dealership data, specifications, and market pricing.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/listings\nGET https://api.auto.dev/listings/{vin}\n```\n\nReturns vehicle listings. Without a VIN, returns an array of listings (typically 100 per page). With a VIN, returns a single specific listing.\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/listings\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to find a specific listing for (optional path parameter) | |\n\n## Pagination\n\nPagination is supported for large result sets.\n\nUse the `page` parameter to navigate through the results. For example, `page=2` will return the second page of results.\n\nLimit the number of results per page using the `limit` parameter. For example, `limit=10` will return 10 results per page.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `page` | number | Page number to retrieve (starting from 1) | 1 |\n| `limit` | number | Number of listings to return per page (1-100) | 100 |\n\n```http\nhttps://api.auto.dev/listings?page=2&limit=50\n```\n\n## Location Filtering\n\nFilter listings by geographic location using the `zip` and `distance` parameters.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `zip` | string | 5-digit ZIP code to center the search around | |\n| `distance` | number | Radius in miles from the ZIP code to include in results | 50 |\n\n```http\nhttps://api.auto.dev/listings?zip=33132&distance=50\n```\n\n## Search Listings\n\nSimply make a GET request to listings with your desired search parameters. You can filter by make, model, year, price, mileage, and more. Add `.not` to the end of the parameter name to exclude values. Use commas to specify multiple values.\n\n```http\nhttps://api.auto.dev/listings?vehicle.make=ford&vehicle.model=mustang\n```\n\n```http\nhttps://api.auto.dev/listings?vehicle.fuel.not=*gas*,diesel\n```\n\n### Vehicle Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.squishVin` | string | The WMI and vehicle descriptor section of the VIN (first 11 characters minus the check digit). Use comma for multiple: 1FA6P8AMF5,137FA5733E | |\n| `vehicle.year` | number | The year of the vehicle. Use specific year (2018) or range (2018-2020) | |\n| `vehicle.make` | string | Vehicle manufacturer. Use comma for multiple: Ford,Chevrolet | |\n| `vehicle.model` | string | Vehicle model. Use comma for multiple: F-150,Silverado | |\n| `vehicle.trim` | string | Trim level. Use comma for multiple: XLT,LT | |\n| `vehicle.bodyStyle` | string | Body style. Use comma for multiple: sedan,coupe | |\n| `vehicle.engine` | string | Engine size. Use comma for multiple: 2.0L,3.5L | |\n| `vehicle.transmission` | string | Transmission type. Use comma for multiple: automatic,manual | |\n| `vehicle.interiorColor` | string | Interior color. Use comma for multiple: black,gray | |\n| `vehicle.exteriorColor` | string | Exterior color. Use comma for multiple: white,black | |\n| `vehicle.doors` | number | Number of doors (2, 4, 5) | |\n\n### Retail Listing Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `retailListing.price` | number | Vehicle price. Use range: 10000-20000 | |\n| `retailListing.state` | string | State where vehicle is located (e.g., CA) | |\n| `retailListing.miles` | number | Vehicle mileage. Use range: 10000-20000 | |\n\n### Wholesale Listing Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `wholesaleListing.buyNowPrice` | number | Wholesale buy now price. Use range: 10000-20000 | |\n| `wholesaleListing.state` | string | State where vehicle is located (e.g., CA) | |\n| `wholesaleListing.miles` | number | Vehicle mileage. Use range: 10000-20000 | |\n\nFor example, to find Toyota Camrys under $30k in California:\n\n```http\nhttps://api.auto.dev/listings?vehicle.make=Toyota&vehicle.model=Camry&retailListing.price=1-30000&retailListing.state=CA\n```\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/listings/10ARJYBS7RC154562\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/listings/10ARJYBS7RC154562', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst result = await response.json()\nconst listings = result.data\nconsole.log(`Found ${listings.length} listings`)\nlistings.forEach((listing) => {\n console.log(\n `${listing.vehicle.year} ${listing.vehicle.make} ${listing.vehicle.model} - $${listing.retailListing?.price || 0}`,\n )\n})\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/listings/10ARJYBS7RC154562',\n headers=headers\n)\n\nresult = response.json()\nfor listing in result['data']:\n vehicle = listing['vehicle']\n price = listing['retailListing']['price'] if listing['retailListing'] else 0\n print(f\"{vehicle['year']} {vehicle['make']} {vehicle['model']} - ${price}\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/listings/10ARJYBS7RC154562',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$result = json_decode($response, true);\nforeach ($result['data'] as $listing) {\n $vehicle = $listing['vehicle'];\n $price = $listing['retailListing']['price'] ?? 0;\n echo \"{$vehicle['year']} {$vehicle['make']} {$vehicle['model']} - \\${$price}\\n\";\n}\n?>\n```\n\n## Response Structure\n\n### Single Listing Object Structure\n\nBoth endpoints return listing objects with the same structure, but wrapped differently:\n\n- **`/listings`** wraps them in: `{data: [array of listing objects]}`\n- **`/listings/{vin}`** wraps them in: `{data: {single listing object}}`\n\nEach listing object contains:\n\n### Basic Listing Fields\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | Vehicle Identification Number | |\n| `location` | number[] | Geographic coordinates [longitude, latitude] | |\n| `createdAt` | string | Timestamp when the listing was created (YYYY-MM-DD HH:MM:SS UTC) | |\n| `online` | boolean | Whether the listing is available online | |\n\n### Vehicle Information\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.squishVin` | string | VIN with model year and check digit removed | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.trim` | string | Trim level designation | |\n| `vehicle.drivetrain` | string | Drivetrain configuration (4WD, AWD, FWD, RWD) | |\n| `vehicle.engine` | string | Engine description and fuel type | |\n| `vehicle.fuel` | string | Fuel type (Gasoline, Plug-In Hybrid, etc.) | |\n| `vehicle.transmission` | string | Transmission type | |\n| `vehicle.confidence` | number | Data accuracy confidence score (0.0 to 1.0) | |\n| `vehicle.doors` | number | Number of doors | |\n| `vehicle.seats` | number | Seating capacity | |\n| `vehicle.exteriorColor` | string | Exterior color name | |\n| `vehicle.interiorColor` | string | Interior color name | |\n\n### Retail Listing Details\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `retailListing.vdp` | string | Vehicle detail page URL | |\n| `retailListing.price` | number | Current asking price in USD | |\n| `retailListing.miles` | number | Vehicle mileage/odometer reading | |\n| `retailListing.used` | boolean | Whether this is a used vehicle listing | |\n| `retailListing.cpo` | boolean | Certified Pre-Owned status | |\n| `retailListing.carfaxUrl` | string | Carfax vehicle history report URL | |\n| `retailListing.dealer` | string | Dealership name | |\n| `retailListing.city` | string | Dealership city | |\n| `retailListing.state` | string | Dealership state abbreviation | |\n| `retailListing.zip` | string | Dealership ZIP code | |\n| `retailListing.primaryImage` | string | Primary vehicle photo URL | |\n| `retailListing.photoCount` | number | Total number of photos available | |\n\n### Additional Data Fields\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `wholesaleListing` | object | null | Wholesale listing information (typically null) | |\n| `history` | object | null | Vehicle history information (typically null) | |\n\n## Example Responses\n\n### Single VIN Response (/listings/{vin})\n\nWhen querying a specific VIN, the API returns a single listing object wrapped in a `data` property:\n\n```json\n{\n \"data\": {\n \"@id\": \"https://api.auto.dev/listings/10ARJYBS7RC154562\",\n \"vin\": \"10ARJYBS7RC154562\",\n \"location\": [-77.0334, 40.2476],\n \"createdAt\": \"2025-09-14 14:04:06\",\n \"online\": true,\n \"vehicle\": {\n \"vin\": \"10ARJYBS7RC154562\",\n \"squishVin\": \"10ARJYBSRC\",\n \"year\": 2024,\n \"make\": \"Jeep\",\n \"model\": \"Grand Cherokee\",\n \"trim\": \"4xe\",\n \"drivetrain\": \"4WD\",\n \"engine\": \"Plug-In Hybrid\",\n \"fuel\": \"Plug-In Hybrid\",\n \"transmission\": \"Automatic\",\n \"confidence\": 0.005,\n \"doors\": 4,\n \"seats\": 5\n },\n \"wholesaleListing\": null,\n \"retailListing\": {\n \"vdp\": \"http://details.vast.com/details/cars/ob-48ae10cec45c5264c0c05239af7ac2c3eda678223f9171ac63be6a3107cd3db63b027b96ef83ac88fd6ccb42933d4f3c6bf26f82a637df6dbf6160746a741de2e12135dcbeff82654b855069fa243842784cfba33bf3b93b6d5a9156baa8b0f948d0b715b4936664c48f9fdb248501ca1a015077c28df814c6ae254e205e6b8afb7f16011f22412ebedeee38685f0721f74c31246e538ff42db94d2ceb09e6950fb15e40f90d9a2a0fa486f173a58cc4/?pl=19\",\n \"price\": 0,\n \"used\": false,\n \"cpo\": false,\n \"carfaxUrl\": \"https://www.carfax.com/VehicleHistory/p/Report.cfx?vin=10ARJYBS7RC154562&partner=FRD_2\",\n \"dealer\": \"Faulkner Dodge Ram Mechanicsburg New\",\n \"city\": \"Mechanicsburg\",\n \"state\": \"PA\",\n \"zip\": \"17050\",\n \"primaryImage\": \"https://retail.photos.vin/10ARJYBS7RC154562-1.jpg\",\n \"photoCount\": 1\n },\n \"history\": null\n }\n}\n```\n\n### All Listings Response (/listings)\n\nWhen querying all listings, the API returns an array of listing objects in the `data` property:\n\n```json\n{\n \"data\": [\n {\n \"@id\": \"https://api.auto.dev/listings/10ARJYBS7RC154562\",\n \"vin\": \"10ARJYBS7RC154562\",\n \"location\": [-77.0334, 40.2476],\n \"createdAt\": \"2025-09-14 14:04:06\",\n \"online\": true,\n \"vehicle\": {\n \"vin\": \"10ARJYBS7RC154562\",\n \"squishVin\": \"10ARJYBSRC\",\n \"year\": 2024,\n \"make\": \"Jeep\",\n \"model\": \"Grand Cherokee\",\n \"trim\": \"4xe\",\n \"drivetrain\": \"4WD\",\n \"engine\": \"Plug-In Hybrid\",\n \"fuel\": \"Plug-In Hybrid\",\n \"transmission\": \"Automatic\",\n \"confidence\": 0.005,\n \"doors\": 4,\n \"seats\": 5\n },\n \"wholesaleListing\": null,\n \"retailListing\": {\n \"vdp\": \"http://details.vast.com/details/cars/ob-48ae10cec45c5264c0c05239af7ac2c3eda678223f9171ac63be6a3107cd3db63b027b96ef83ac88fd6ccb42933d4f3c6bf26f82a637df6dbf6160746a741de2e12135dcbeff82654b855069fa243842784cfba33bf3b93b6d5a9156baa8b0f948d0b715b4936664c48f9fdb248501ca1a015077c28df814c6ae254e205e6b8afb7f16011f22412ebedeee38685f0721f74c31246e538ff42db94d2ceb09e6950fb15e40f90d9a2a0fa486f173a58cc4/?pl=19\",\n \"price\": 0,\n \"used\": false,\n \"cpo\": false,\n \"carfaxUrl\": \"https://www.carfax.com/VehicleHistory/p/Report.cfx?vin=10ARJYBS7RC154562&partner=FRD_2\",\n \"dealer\": \"Faulkner Dodge Ram Mechanicsburg New\",\n \"city\": \"Mechanicsburg\",\n \"state\": \"PA\",\n \"zip\": \"17050\",\n \"primaryImage\": \"https://retail.photos.vin/10ARJYBS7RC154562-1.jpg\",\n \"photoCount\": 1\n },\n \"history\": null\n },\n {\n \"@id\": \"https://api.auto.dev/listings/137ZA90311E190871\",\n \"vin\": \"137ZA90311E190871\",\n \"location\": [-86.111777, 39.924385],\n \"createdAt\": \"2025-02-27 01:56:02\",\n \"online\": false,\n \"vehicle\": {\n \"vin\": \"137ZA90311E190871\",\n \"squishVin\": \"137ZA9031E\",\n \"year\": 2001,\n \"make\": \"AM General\",\n \"model\": \"Hummer\",\n \"trim\": \"Open Top\"\n },\n \"wholesaleListing\": {\n \"auction\": \"OVE\",\n \"miles\": 89868\n },\n \"retailListing\": {\n \"price\": 119000,\n \"dealer\": \"Indy Cars & Trucks\",\n \"city\": \"Indianapolis\",\n \"state\": \"IN\"\n },\n \"history\": {\n \"accidents\": false,\n \"ownerCount\": 7\n }\n }\n ]\n}\n```\n\n## Error Responses\n\n### Invalid Parameter\n\n```json\n{\n \"status\": 400,\n \"error\": \"Invalid parameter provided: make. This parameter does not exist in this endpoint.\",\n \"code\": \"INVALID_PARAMETER\",\n \"path\": \"/listings\",\n \"requestId\": \"966e8386bb38f095\"\n}\n```\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"Invalid VIN format: \\\"123INVALID\\\" - VIN must be exactly 17 characters\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/listings/123INVALID\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"Resource \\\"1FTFW3LDXRFB40317\\\" not found\",\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"path\": \"/listings/1FTFW3LDXRFB40317\",\n \"requestId\": \"966716ac29ed8147\"\n}\n```\n\n## Interactive API Reference\n\nReady to test these endpoints? Use our interactive API playground to make live requests and see real responses.\n\n\n \n \n\n\n## Plan Availability\n\n- **Starter**: ✅ Available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "vehicle-payments": "Calculate detailed vehicle payment information including loan amounts, monthly payments, taxes, fees, and complete cost breakdowns. Get accurate financing estimates based on vehicle details, purchase price, location, and loan terms.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/payments/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/payments/1C4RJFAG0FC625797?price=25000&zip=55414&docFee=200&tradeIn=0&downPayment=5000&loanTerm=60\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `price` | string | Vehicle sales price | |\n| `zip` | string | 5-digit ZIP code for tax and fee calculations | |\n| `docFee` | number | Dealer documentation fee | |\n| `tradeIn` | string | Trade-in vehicle value | 0 |\n| `downPayment` | number | Down payment amount | |\n| `loanTerm` | number | Loan term in months | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/payments/1C4RJFAG0FC625797?price=25000&zip=55414&docFee=200&tradeIn=0&downPayment=5000&loanTerm=60\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch(\n 'https://api.auto.dev/payments/1C4RJFAG0FC625797?price=25000&zip=55414&docFee=200&tradeIn=0&downPayment=5000&loanTerm=60',\n {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n },\n)\n\nconst payments = await response.json()\nconsole.log(payments.paymentsData)\n```\n\n```python tab=\"Python\"\n\nurl = 'https://api.auto.dev/payments/1C4RJFAG0FC625797'\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nparams = {\n 'price': '25000',\n 'zip': '55414',\n 'docFee': 200,\n 'tradeIn': '0',\n 'downPayment': 5000,\n 'loanTerm': 60\n}\n\nresponse = requests.get(url, headers=headers, params=params)\npayments = response.json()\nprint(payments['paymentsData'])\n```\n\n```php tab=\"PHP\"\n '25000',\n 'zip' => '55414',\n 'docFee' => 200,\n 'tradeIn' => '0',\n 'downPayment' => 5000,\n 'loanTerm' => 60\n]);\n\n$url = \"https://api.auto.dev/payments/{$vin}?{$queryParams}\";\n\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, $url);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n]);\n\n$response = curl_exec($ch);\n$payments = json_decode($response, true);\necho json_encode($payments['paymentsData']);\ncurl_close($ch);\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `paymentsData.loanAmount` | number | Total amount to be financed after down payment and trade-in | |\n| `paymentsData.loanMonthlyPayment` | number | Monthly loan payment (principal + interest only) | |\n| `paymentsData.loanMonthlyPaymentWithTaxes` | number | Monthly payment including taxes and fees | |\n| `paymentsData.totalTaxesAndFees` | number | Total amount of taxes and fees | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `taxes.combinedSalesTax` | number | Total sales tax amount | |\n| `taxes.stateSalesTax` | number | State-level sales tax | |\n| `taxes.gasGuzzlerTax` | number | Federal gas guzzler tax (if applicable) | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `fees.titleFee` | number | Vehicle title processing fee | |\n| `fees.registrationFee` | number | Vehicle registration fee | |\n| `fees.dmvFee` | number | Total DMV-related fees | |\n| `fees.combinedFees` | number | Sum of all fees | |\n| `fees.docFee` | number | Dealer documentation fee | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `apr.36` | number | 36-month loan APR percentage | |\n| `apr.48` | number | 48-month loan APR percentage | |\n| `apr.60` | number | 60-month loan APR percentage | |\n| `apr.72` | number | 72-month loan APR percentage | |\n| `apr.84` | number | 84-month loan APR percentage | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1C4RJFAG0FC625797\",\n \"year\": \"2015\",\n \"make\": \"Jeep\",\n \"model\": \"Grand Cherokee\"\n },\n \"criteria\": {\n \"price\": \"25000\",\n \"zip\": \"55414\",\n \"docFee\": 200,\n \"tradeIn\": \"0\"\n },\n \"paymentsData\": {\n \"loanAmount\": 21952.49,\n \"loanMonthlyPayment\": 363.83,\n \"loanMonthlyPaymentWithTaxes\": 399.35,\n \"totalTaxesAndFees\": 1952.49,\n \"taxes\": {\n \"combinedSalesTax\": 1625,\n \"stateSalesTax\": 1625,\n \"gasGuzzlerTax\": 0\n },\n \"fees\": {\n \"titleFee\": 8.25,\n \"registrationFee\": 70.99,\n \"dmvFee\": 48.25,\n \"combinedFees\": 327.49,\n \"docFee\": 200,\n \"dmvFees\": {\n \"Filing Fee\": 7,\n \"License Plate Fee\": 15.5,\n \"Public Safety Vehicle Fee\": 3.5,\n \"Technology Fee\": 2.25,\n \"Wheelage Tax\": 20\n }\n },\n \"calculationCriteria\": {\n \"numberOfMonths\": 60,\n \"financeRate\": 3.5,\n \"downPayment\": 5000,\n \"tradeIn\": 0,\n \"tradeInOwedAmount\": 0,\n \"salesPrice\": 25000,\n \"conditionalIncentiveAmount\": 0,\n \"primaryIncentiveAmount\": 0,\n \"docFee\": 200,\n \"zipCode\": \"55414\",\n \"styleId\": 200701040,\n \"marketValue\": 25000,\n \"withConcreteTaxesAndFees\": true,\n \"applyLimits\": true,\n \"msrp\": 25000,\n \"lowerLimit\": false\n }\n },\n \"apr\": {\n \"36\": 9.25,\n \"48\": 9.25,\n \"60\": 9.25,\n \"72\": 9.25,\n \"84\": 9.25\n },\n \"totalTaxesAndFees\": 1952.49,\n \"taxes\": {\n \"combinedSalesTax\": 1625,\n \"stateSalesTax\": 1625,\n \"gasGuzzlerTax\": 0\n },\n \"fees\": {\n \"titleFee\": 8.25,\n \"registrationFee\": 70.99,\n \"dmvFee\": 48.25,\n \"combinedFees\": 327.49,\n \"docFee\": 200,\n \"dmvFees\": {\n \"Filing Fee\": 7,\n \"License Plate Fee\": 15.5,\n \"Public Safety Vehicle Fee\": 3.5,\n \"Technology Fee\": 2.25,\n \"Wheelage Tax\": 20\n }\n }\n}\n```\n\n## Use Cases\n\n- **Payment Calculators**: Build interactive tools for customers to estimate monthly payments and total costs\n- **Dealership Finance**: Calculate financing options and present payment scenarios to customers\n- **Auto Lending**: Evaluate loan structures and payment terms for different borrower profiles\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/payments/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/payments/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n### Source Error\n\n```json\n{\n \"status\": 503,\n \"error\": \"Payment calculation service temporarily unavailable\",\n \"code\": \"SOURCE_ERROR\",\n \"path\": \"/payments/1GYKPDRSXSZ102995\",\n \"requestId\": \"c3d4e5f6g7h8i9j0\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "vehicle-photos": "Retrieve a collection of high-quality retail images for a specific vehicle based on its VIN. Get comprehensive photo collections including exterior, interior, and detail shots from dealer listings and auction sources.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/photos/{vin}\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve photos for | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/photos/WP0AA2990WS321225\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/photos/WP0AA2990WS321225', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst photos = await response.json()\nconsole.log(`Found ${photos.data.retail.length} retail photos`)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/photos/WP0AA2990WS321225',\n headers=headers\n)\n\nphotos = response.json()\nprint(f\"Retail photos: {len(photos['data']['retail'])}\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/photos/WP0AA2990WS321225',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$photos = json_decode($response, true);\necho \"Retail photos: \" . count($photos['data']['retail']) . \"\\n\";\n?>\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `data.retail` | string[] | Array of retail photo URLs from dealer listings | |\n\n## Example Response\n\n### Vehicle with Photos\n\n```json\n{\n \"data\": {\n \"retail\": [\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-1.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-2.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-3.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-4.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-5.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-6.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-7.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-8.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-9.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-10.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-11.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-12.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-13.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-14.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-15.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-16.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-17.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-18.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-19.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-20.jpg\",\n \"https://api.auto.dev/photos/retail/WP0AA2990WS321225-21.jpg\"\n ]\n }\n}\n```\n\n### Vehicle without Photos\n\nWhen no photos are available for a VIN, the API returns empty arrays instead of an error:\n\n```json\n{\n \"data\": {\n \"retail\": []\n }\n}\n```\n\n## Photo Collection Details\n\n### Photo Sources\n\n**Retail Photos**: Professional dealer listings and inventory photos\n\n- **Format**: JPEG images hosted on Auto.dev CDN\n- **URL Pattern**: `https://api.auto.dev/photos/{source}/{vin}-{number}.jpg`\n- **Availability**: Retail photos are more common; wholesale may be empty\n\n### Typical Photo Content\n\nCollections include exterior shots, interior views, engine bay, detail shots, and any damage documentation. Photos are ordered by importance with primary exterior views first, followed by additional angles, interior, and detail shots.\n\n## Image Specifications\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `format` | string | Image file format | JPEG |\n| `quality` | string | Image quality level | High-resolution retail/auction quality |\n| `dimensions` | string | Typical image dimensions | Varies (typically 800x600 to 1200x800) |\n| `cdn_hosting` | string | Content delivery network | api.auto.dev |\n| `url_pattern` | string | Photo URL structure | |\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 404,\n \"error\": \"This vehicle does not have any photos available. Please try a different VIN.\",\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"path\": \"/photos/123Invalid\",\n \"requestId\": \"966d92f81daff05e\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ✅ Available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "vehicle-recalls": "Get comprehensive vehicle recall information from the National Highway Traffic Safety Administration (NHTSA) database. Access detailed recall notices, safety information, remediation steps, and compliance data for any vehicle to ensure driver and passenger safety.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/recalls/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/recalls/1FTFW3LDXRFB40317\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve recalls for | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/recalls/1FTFW3LDXRFB40317\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/recalls/1FTFW3LDXRFB40317', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst recalls = await response.json()\nconsole.log(`Found ${recalls.data.length} recalls`)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/recalls/1FTFW3LDXRFB40317',\n headers=headers\n)\n\nrecalls = response.json()\nprint(f\"Found {len(recalls['data'])} recalls\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/recalls/1FTFW3LDXRFB40317',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$recalls = json_decode($response, true);\necho \"Found \" . count($recalls['data']) . \" recalls\\n\";\n?>\n```\n\n## Response Structure\n\n### Main Response\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `data` | array | Array of recall records for the specified vehicle | |\n\n### Recall Record Fields\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `manufacturer` | string | Vehicle manufacturer name (e.g., \"Porsche Cars North America, Inc.\") | |\n| `nhtsaCampaignNumber` | string | Official NHTSA recall campaign number | |\n| `parkIt` | boolean | Whether vehicle should not be driven until repaired | |\n| `parkOutSide` | boolean | Whether vehicle should be parked outside due to fire risk | |\n| `overTheAirUpdate` | boolean | Whether recall can be resolved via software update | |\n| `reportReceivedDate` | string | Date NHTSA received the recall report (DD/MM/YYYY format) | |\n| `component` | string | Vehicle component affected by the recall | |\n| `summary` | string | Brief description of the recall issue | |\n| `consequence` | string | Potential consequences if issue is not addressed | |\n| `remedy` | string | Detailed remediation steps and dealer instructions | |\n| `notes` | string | Additional notes and contact information | |\n| `modelYear` | string | Model year of affected vehicle | |\n| `make` | string | Vehicle make (manufacturer) | |\n| `model` | string | Vehicle model name | |\n\n## Example Response\n\n### Vehicle with Recalls\n\n```json\n{\n \"data\": [\n {\n \"manufacturer\": \"Porsche Cars North America, Inc.\",\n \"nhtsaCampaignNumber\": \"21V201000\",\n \"parkIt\": false,\n \"parkOutSide\": false,\n \"overTheAirUpdate\": false,\n \"reportReceivedDate\": \"24/03/2021\",\n \"component\": \"SUSPENSION:REAR\",\n \"summary\": \"Porsche Cars North America, Inc. (Porsche) is recalling certain 2019 Porsche 911 Speedster, 2020 Porsche 911 Carrera S Coupe, Carrera 4S Coupe, and Carrera S Cabriolet vehicles. The screw connection on the rear axle upper control arm may be loose.\",\n \"consequence\": \"A loose connection may fail, causing driving instability and increasing the risk of a crash.\",\n \"remedy\": \"Porsche will notify owners, and dealers will rework and tighten the screw connection on the rear axle upper control arm, free of charge. Owner notification letters were mailed May 21, 2021. Owners may contact Porsche customer service at 1-800-767-7243. Porsche's number for this recall is AMA6.\",\n \"notes\": \"Owners may also contact the National Highway Traffic Safety Administration Vehicle Safety Hotline at 1-888-327-4236 (TTY 1-800-424-9153), or go to www.safercar.gov.\",\n \"modelYear\": \"2019\",\n \"make\": \"PORSCHE\",\n \"model\": \"911\"\n }\n ]\n}\n```\n\n### Vehicle with No Recalls\n\nWhen a valid VIN has no recalls, the API returns an empty array:\n\n```json\n{\n \"data\": []\n}\n```\n\n**Note**: Currently, invalid VINs also return empty arrays, but this should be changed to return proper HTTP error responses (see Error Responses section below).\n\n## Safety Alert Classifications\n\n### Critical Safety Flags\n\n- **Park It** (`parkIt: true`) - Vehicle should not be driven until repaired due to immediate safety risk\n- **Park Outside** (`parkOutSide: true`) - Vehicle should be parked away from structures due to fire/explosion risk\n- **Over-the-Air Update** (`overTheAirUpdate: true`) - Recall can be resolved via software update without dealer visit\n\n### Component Categories\n\nCommon recall components include:\n\n- **Safety-Critical**: BRAKES, STEERING, AIRBAGS, FUEL SYSTEM, ELECTRICAL SYSTEM\n- **Visibility**: EXTERIOR LIGHTING, VISIBILITY, INSTRUMENT PANEL\n- **Structural**: SEATS, DOORS, BODY\n\n## Use Cases\n\n- **Vehicle Safety Apps**: Check for open recalls before purchase decisions and during ownership\n- **Dealership Systems**: Alert customers about recall notifications and schedule service appointments\n- **Fleet Management**: Monitor recall status across vehicle inventory and prioritize critical repairs\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/recalls/1GYKPD\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", - "vin-decode": "The VIN Decode API provides comprehensive vehicle information from any valid 17-character Vehicle Identification Number (VIN) worldwide. Supports vehicles from North America, Europe, Asia, and other global markets.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/vin/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/vin/3GCUDHEL3NG668790\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/vin/3GCUDHEL3NG668790\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/vin/3GCUDHEL3NG668790', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst result = await response.json()\nconsole.log(result.make)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/vin/3GCUDHEL3NG668790',\n headers=headers\n)\n\nresult = response.json()\nprint(result)\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/vin/3GCUDHEL3NG668790',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$result = json_decode($response, true);\nprint_r($result);\n?>\n```\n\n## Example Response\n\n```json\n{\n \"vin\": \"3GCUDHEL3NG668790\",\n \"vinValid\": true,\n \"wmi\": \"3GC\",\n \"origin\": \"Mexico\",\n \"squishVin\": \"3GCUDHELNG\",\n \"checkDigit\": \"3\",\n \"checksum\": true,\n \"type\": \"Active\",\n \"make\": \"Chevrolet\",\n \"model\": \"Silverado 1500\",\n \"trim\": \"ZR2\",\n \"style\": \"4x4 4dr Crew Cab 5.8 ft. SB\",\n \"body\": \"Truck\",\n \"engine\": \"5.3L V8 OHV 16V FFV\",\n \"drive\": \"4WD\",\n \"transmission\": \"Automatic\",\n \"vehicle\": {\n \"vin\": \"3GCUDHEL3NG668790\",\n \"year\": 2022,\n \"make\": \"Chevrolet\",\n \"model\": \"Silverado 1500\",\n \"manufacturer\": \"General Motors de Mexico\"\n },\n \"ambiguous\": false\n}\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | Vehicle Identification Number | |\n| `vinValid` | boolean | Whether the VIN is valid and properly formatted | |\n| `wmi` | string | World Manufacturer Identifier (first 3 characters) | |\n| `origin` | string | Country of manufacture | |\n| `squishVin` | string | VIN with model year and check digit removed | |\n| `checkDigit` | string | The 9th character used for VIN validation | |\n| `checksum` | boolean | Whether the VIN checksum is valid | |\n| `type` | string | Vehicle type classification | |\n| `make` | string | Vehicle manufacturer | |\n| `model` | string | Vehicle model name | |\n| `trim` | string | Trim level designation | |\n| `style` | string | Body style and configuration (e.g., \"4x4 4dr Crew Cab 5.8 ft. SB\") | |\n| `body` | string | Vehicle body class | |\n| `engine` | string | Engine description | |\n| `drive` | string | Drivetrain configuration | |\n| `transmission` | string | Transmission type | |\n| `vehicle.vin` | string | Vehicle Identification Number (nested object) | |\n| `vehicle.year` | number | Model year (nested object) | |\n| `vehicle.make` | string | Vehicle manufacturer (nested object) | |\n| `vehicle.model` | string | Vehicle model name (nested object) | |\n| `vehicle.manufacturer` | string | Full manufacturer name (nested object) | |\n| `ambiguous` | boolean | Whether the VIN corresponds to multiple possible vehicle trims | |\n\n## Use Cases\n\n- **Vehicle Identification**: Validate VIN format and verify vehicle authenticity for purchase decisions\n- **Insurance Applications**: Get essential vehicle details for policy creation and risk assessment\n- **Fleet Management**: Track and catalog vehicle information across large fleets and inventory systems\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/vin/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/vin/3GCUDHEL3NG668790\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Starter**: ✅ Available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n" + "interest-rates": "Get current interest rates for auto loans, leases, and other financing options. Retrieve personalized rates based on vehicle details, credit score, location, and loan terms.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/apr/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `year` | number | Model year of the vehicle | |\n| `make` | string | Vehicle manufacturer | |\n| `model` | string | Vehicle model name | |\n| `zip` | string | 5-digit ZIP code for location-based rates | |\n| `creditScore` | string | Credit score for rate calculation | |\n| `vehicleAge` | number | Age of the vehicle in years | |\n| `vehicleMileage` | string | Current vehicle mileage | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch(\n 'https://api.auto.dev/apr/1C4HJXEN5MW592818?year=2021&make=Jeep&model=Wrangler&zip=37129&creditScore=720&vehicleAge=3&vehicleMileage=36000',\n {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n },\n)\n\nconst rates = await response.json()\nconsole.log(rates.apr)\n```\n\n```python tab=\"Python\"\n\nurl = 'https://api.auto.dev/apr/1C4HJXEN5MW592818'\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nparams = {\n 'year': 2021,\n 'make': 'Jeep',\n 'model': 'Wrangler',\n 'zip': '37129',\n 'creditScore': '720',\n 'vehicleAge': 3,\n 'vehicleMileage': '36000'\n}\n\nresponse = requests.get(url, headers=headers, params=params)\nrates = response.json()\nprint(rates['apr'])\n```\n\n```php tab=\"PHP\"\n 2021,\n 'make' => 'Jeep',\n 'model' => 'Wrangler',\n 'zip' => '37129',\n 'creditScore' => '720',\n 'vehicleAge' => 3,\n 'vehicleMileage' => '36000'\n]);\n\n$url = \"https://api.auto.dev/apr/{$vin}?{$queryParams}\";\n\n$ch = curl_init();\ncurl_setopt($ch, CURLOPT_URL, $url);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n]);\n\n$response = curl_exec($ch);\n$rates = json_decode($response, true);\necho json_encode($rates['apr']);\ncurl_close($ch);\n?>\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle` | object | Vehicle information used for rate calculation | |\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model | |\n| `zip` | string | ZIP code used for location-based rates | |\n| `creditScore` | string | Credit score used for rate calculation | |\n| `vehicleAge` | number | Age of vehicle in years | |\n| `vehicleMileage` | string | Vehicle mileage | |\n| `apr` | object | Interest rates by loan term in months | |\n| `apr.36` | number | 36-month loan APR percentage | |\n| `apr.48` | number | 48-month loan APR percentage | |\n| `apr.60` | number | 60-month loan APR percentage | |\n| `apr.72` | number | 72-month loan APR percentage | |\n| `apr.84` | number | 84-month loan APR percentage | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1C4HJXEN5MW592818\",\n \"year\": 2021,\n \"make\": \"Jeep\",\n \"model\": \"Wrangler\"\n },\n \"zip\": \"37129\",\n \"creditScore\": \"720\",\n \"vehicleAge\": 3,\n \"vehicleMileage\": \"36000\",\n \"apr\": {\n \"36\": 7.644,\n \"48\": 7.644,\n \"60\": 7.524,\n \"72\": 7.663,\n \"84\": 8.263\n }\n}\n```\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/apr/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/apr/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "oem-build-data": "Retrieve complete vehicle build information based on the VIN, including exact trim details, drivetrain, engine specifications, interior/exterior colors, factory options, and MSRP data. This comprehensive API provides the most detailed vehicle information available from OEM build records.\n\nIf you do not have a VIN, the [vehicle catalog](#vehicle-catalog) lists makes and models with the model years recorded for each, in a single request.\n\nA VIN that decodes to a car but has no build record answers `207 Multi-Status` with the vehicle and what its style ships with, never a fabricated build. See [partial answers](#partial-answers-207). A build that lacks a color or its options says so in [`missing`](#missing-fields).\n\n## Endpoint\n\n```\nGET https://api.auto.dev/build/{vin}\n```\n\nTo browse the catalog without a VIN, see the [vehicle catalog](#vehicle-catalog) below.\n\n```\nGET https://api.auto.dev/build/ymm\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/build/1FTFW3LDXRFB40317\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/build/1FTFW3LDXRFB40317\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/build/1FTFW3LDXRFB40317', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst buildData = await response.json()\nconsole.log(buildData.build)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/build/1FTFW3LDXRFB40317',\n headers=headers\n)\n\nbuild_data = response.json()\nprint(build_data['build'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/build/1FTFW3LDXRFB40317',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$buildData = json_decode($response, true);\nprint_r($buildData['build']);\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.vin` | string | Vehicle Identification Number | |\n| `build.year` | number | Model year | |\n| `build.make` | string | Vehicle manufacturer | |\n| `build.model` | string | Vehicle model name | |\n| `build.trim` | string | Complete trim designation | |\n| `build.series` | string | Vehicle series or sub-model | |\n| `build.style` | string | Body style designation (e.g., \"4D Crossover\") | |\n| `build.drivetrain` | string | Drivetrain configuration (e.g., \"RWD\", \"AWD\") | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.engine` | string | Complete engine specification with displacement, configuration, and horsepower | |\n| `build.transmission` | string | Transmission type and configuration | |\n| `build.confidence` | number | Data accuracy confidence score (0-1) | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.interiorColor` | object | Interior color name and hex code mapping | |\n| `build.exteriorColor` | object | Exterior color name and hex code mapping | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.options` | object | Factory option codes mapped to descriptions | |\n| `build.optionsMsrp` | number | Total MSRP value of factory options in USD | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `build.headUpDisplay` | boolean | Whether the vehicle has a head-up display, detected from the factory equipment list. Returned where the manufacturer provides a full equipment list; false means the feature is not in the returned list. | |\n| `build.rainSensingWipers` | boolean | Whether the vehicle has rain-sensing wipers, detected from the factory equipment list. Returned where the manufacturer provides a full equipment list; false means the feature is not in the returned list. | |\n\n## Example Response\n\n```json\n{\n \"build\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2024,\n \"make\": \"Ford\",\n \"model\": \"F-150\",\n \"trim\": \"XLT\",\n \"series\": \"XLT\",\n \"style\": \"4D SuperCrew\",\n \"drivetrain\": \"4WD\",\n \"engine\": \"3.5L V-6 gasoline direct injection, DOHC, twin turbocharged, regular unleaded, engine with 400HP\",\n \"transmission\": \"10-speed automatic\",\n \"confidence\": 0.99,\n \"interiorColor\": {\n \"Black Onyx\": \"#1C1C1C\"\n },\n \"exteriorColor\": {\n \"Iconic Silver Metallic\": \"#C0C0C0\"\n },\n \"options\": {\n \"53A\": \"XLT Mid Equipment Group\",\n \"99N\": \"Iconic Silver Metallic\",\n \"FX4\": \"FX4 Off-Road Package\",\n \"86M\": \"Trailer Tow Package\"\n },\n \"optionsMsrp\": 4295,\n \"headUpDisplay\": false,\n \"rainSensingWipers\": false\n }\n}\n```\n\n## Missing Fields\n\nA `200` is what the record for this VIN says. When no record held one of `interiorColor`, `exteriorColor` or `options`, the response lists it in a top-level `missing` array. The key is absent when nothing is missing, and `build` is the same either way.\n\n```json\n{\n \"build\": {\n \"vin\": \"19XFL2H80TE045314\",\n \"year\": 2026,\n \"make\": \"Honda\",\n \"model\": \"Civic Hatchback\",\n \"trim\": \"Sport\",\n \"style\": \"Hatchback 4D\",\n \"drivetrain\": \"FWD\",\n \"engine\": \"2.0L I4\",\n \"transmission\": \"CVT\",\n \"confidence\": 0.85,\n \"options\": {},\n \"headUpDisplay\": false,\n \"rainSensingWipers\": false\n },\n \"missing\": [\n { \"field\": \"interiorColor\", \"reason\": \"no_vin_record\" },\n { \"field\": \"exteriorColor\", \"reason\": \"no_vin_record\" }\n ]\n}\n```\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `.field` | string | The build key no record held: `interiorColor`, `exteriorColor` or `options`. | |\n| `.reason` | string | `no_vin_record`: no record holds this field for this VIN. `not_yet_available`: the model year is ahead of the catalogs; ask again later in the model year. | |\n\nAn empty `options` object is not always a gap. The example above is a **base vehicle**: the record names the trim and lists nothing optional, so `options: {}` is the answer and only the colors are missing. `options` appears in `missing` only when a record exists for the VIN but holds no option list.\n\nA build with missing fields bills as a full build.\n\n## Partial Answers (207)\n\nWhen a VIN decodes to a car but no record builds it, `/build` answers **`207 Multi-Status`** instead of a 404: the vehicle the decoder named, `build: null`, what the matched style ships with, and why. A catalog option carries the manufacturer's `code` when it is known, and `code: null` otherwise; a catalog code says the style offers the option, not that this VIN has it.\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1C4RJHBR3V8175351\",\n \"year\": 2027,\n \"make\": \"Jeep\",\n \"model\": \"Grand Cherokee\",\n \"body\": \"Suv 4D\"\n },\n \"build\": null,\n \"catalog\": {\n \"vinSpecific\": false,\n \"styles\": [\n {\n \"styleId\": \"402111461\",\n \"name\": \"Limited Reserve 4dr SUV 4WD (2.0L 4cyl Turbo 8A)\",\n \"trim\": \"Limited Reserve\",\n \"confidence\": 0.85,\n \"msrp\": 52555\n },\n {\n \"styleId\": \"402111460\",\n \"name\": \"Limited 4dr SUV 4WD (2.0L 4cyl Turbo 8A)\",\n \"trim\": \"Limited\",\n \"confidence\": 0.15,\n \"msrp\": 46960\n }\n ],\n \"standardEquipment\": [\"Dual fuel injection\", \"Full time 4WD\", \"Electronic single speed\"],\n \"availableOptions\": [\n { \"code\": null, \"name\": \"Mopar finishing package\" },\n { \"code\": null, \"name\": \"Trailer tow package\" }\n ],\n \"exteriorColors\": [\n { \"name\": \"Sting-Gray Clear Coat\", \"colorCode\": \"#5E5E5E\" },\n { \"name\": \"High Gloss Black\", \"colorCode\": \"#000000\" }\n ],\n \"interiorColors\": [{ \"name\": \"Global Black, leatherette\", \"colorCode\": \"#000000\" }]\n },\n \"reason\": \"not_yet_available\",\n \"retryable\": true\n}\n```\n\nA 207 passes the `ok` check of most HTTP clients, and `build` is `null`. Branch on the status, or on `build === null`, before reading `build`:\n\n```javascript tab=\"JavaScript\"\nconst res = await fetch(`https://api.auto.dev/build/${vin}`, {\n headers: { Authorization: 'Bearer YOUR_API_KEY' },\n})\nconst data = await res.json()\n\nif (res.status === 207) {\n // data.vehicle names the car; data.build is null; data.catalog is what the style ships with, or null.\n // data.reason says why; ask again later when data.retryable is true.\n} else if (res.ok) {\n console.log(data.build)\n}\n```\n\n```python tab=\"Python\"\n\nres = requests.get(f'https://api.auto.dev/build/{vin}', headers={'Authorization': 'Bearer YOUR_API_KEY'})\ndata = res.json()\n\nif res.status_code == 207:\n # data['vehicle'] names the car; data['build'] is None; data['catalog'] is the style's, or None.\n # data['reason'] says why; ask again later when data['retryable'] is true.\n pass\nelif res.ok:\n print(data['build'])\n```\n\n### Response Structure (207)\n\n\n\nWhat a decoder said about this VIN. No options, no colors, never a fabricated build.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.trim` | string | Trim, only when a record pinned it for this VIN. | |\n| `vehicle.body` | string | Body style, when known (e.g., \"Suv 4D\"). | |\n| `vehicle.msrp` | number | Base MSRP in USD, only when `catalog.styles` holds one style. | |\n| `build` | null | Always `null` on a 207. | |\n\n\n\nWhat the matched style ships with. It is the style's, not this VIN's: `vinSpecific` is always `false`. `catalog` is `null` when no style is known for the VIN, or when the reason is `market_not_covered` or `class_not_covered`.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `catalog.vinSpecific` | boolean | Always `false`: the catalog describes the style, not what was installed on this VIN. | |\n| `catalog.styles` | | | |\n| `catalog.standardEquipment` | string[] | Feature names the style lists as standard. | |\n| `catalog.availableOptions` | | | |\n| `catalog.exteriorColors` | | | |\n| `catalog.interiorColors` | array | Interior colors the style offers, in the same shape. | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `reason` | string | Why there is no build for this VIN. One of the codes below. | |\n| `retryable` | boolean | Whether asking again later can change the answer. `true` only for `not_yet_available`. | |\n\n### Reason Codes\n\nEvery miss, 207 or 404, carries `reason` and `retryable`. \"If decoded\" means a decoder named the year, make and model; otherwise the same reason rides a 404.\n\n| `reason` | status | means | retry |\n| -------------------- | ------------------------ | --------------------------------------------------------------- | ------------------------------------------ |\n| `not_yet_available` | 207 if decoded, else 404 | model year ahead of the catalogs | yes, the catalogs catch up within the year |\n| `no_build_record` | 207 if decoded, else 404 | no record builds this VIN | no |\n| `market_not_covered` | 207 if decoded, else 404 | non-North-American VIN; `catalog` is `null` | no |\n| `class_not_covered` | 207 if decoded, else 404 | motorcycle, trailer or heavy truck; `catalog` is `null` | no |\n| `invalid_vin` | 404 | the check digit does not compute, or the VIN is a test pattern | no |\n\nA vehicle-only 207, a motorcycle outside build coverage:\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1HD1BWV10GB016330\",\n \"year\": 2016,\n \"make\": \"Harley-davidson\",\n \"model\": \"Flstc103 / Heritage Softail Classic\",\n \"body\": \"Motorcycle - Custom\"\n },\n \"build\": null,\n \"catalog\": null,\n \"reason\": \"class_not_covered\",\n \"retryable\": false\n}\n```\n\nA 404 is reserved for a VIN no decoder can name. See [error responses](#error-responses).\n\n### Billing\n\nA 207 is not a billed call and counts toward no quota.\n\n## Vehicle Catalog\n\nLists the makes and models in the build catalog, with the model years recorded for\neach. **No VIN is required**, and the catalog is returned in a single request.\n\nThe catalog is a reference list rather than a statement of coverage: a make and model\nappearing here does not guarantee a build record for a particular VIN, and a vehicle\nabsent from it may still decode. Use it to browse and to build pickers; use\n`GET /build/{vin}` to find out what exists for a specific vehicle.\n\n```\nGET https://api.auto.dev/build/ymm\n```\n\n```http\nhttps://api.auto.dev/build/ymm\n```\n\nThis endpoint takes no parameters.\n\n### Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/build/ymm\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/build/ymm', {\n headers: { Authorization: 'Bearer YOUR_API_KEY' },\n})\n\nconst catalog = await response.json()\nconst toyotaModels = Object.keys(catalog.Toyota)\n```\n\n```python tab=\"Python\"\n\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\ncatalog = requests.get('https://api.auto.dev/build/ymm', headers=headers).json()\ntoyota_models = list(catalog['Toyota'].keys())\n```\n\n### Response Structure\n\nEach top-level key is a make. Each value maps a model name to the years covered.\n\n```json\n{\n \"Toyota\": {\n \"4Runner\": \"1987-2026\",\n \"86\": \"2017-2020\"\n },\n \"Acura\": {\n \"ILX\": \"2013-2022\"\n }\n}\n```\n\n### Billing\n\nCatalog requests bill as OEM Build Data, at the same rate as a VIN lookup. Repeated\ncatalog requests within the same day count once.\n\n## Use Cases\n\n- **Appraisal Services**: Factor in factory options and original colors for accurate vehicle valuations\n- **Insurance Underwriting**: Use confidence scores and build specifications for risk assessment\n- **Parts & Service**: Match exact factory option codes for correct parts ordering\n- **Catalog & Search**: Build make/model pickers and check coverage before looking up a VIN\n\n## Error Responses\n\n### Invalid VIN\n\nThe VIN is not 17 valid characters. A well-formed VIN that is not a vehicle is a 404 `INVALID_VIN` instead (below).\n\n```json\n{\n \"error\": {\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/build/1FTFW3LDXRFB4031\",\n \"requestId\": \"a4b064e6ab9ba558\"\n }\n}\n```\n\n### VIN Not Found\n\nA 404 means no decoder could name the car, or the VIN is not a vehicle. A car a decoder names, with no build record, is a [207](#partial-answers-207), not a 404. Every miss carries `reason` and `retryable`, top-level and inside `error`.\n\n```json\n{\n \"build\": {\n \"error\": \"No build data available\",\n \"vin\": \"1FMDU32X6RUE08716\"\n },\n \"reason\": \"no_build_record\",\n \"retryable\": false,\n \"error\": {\n \"status\": 404,\n \"error\": \"No build data available for this vehicle.\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/build/1FMDU32X6RUE08716\",\n \"requestId\": \"nu9cn44nt2ek5rbk\",\n \"reason\": \"no_build_record\",\n \"retryable\": false\n }\n}\n```\n\n### Not a Vehicle\n\nThe check digit does not compute, or the VIN is a test pattern.\n\n```json\n{\n \"build\": {\n \"error\": \"No build data available\",\n \"vin\": \"11111111111111111\"\n },\n \"reason\": \"invalid_vin\",\n \"retryable\": false,\n \"error\": {\n \"status\": 404,\n \"error\": \"This VIN is not a vehicle: its check digit does not compute, or it is a test pattern.\",\n \"code\": \"INVALID_VIN\",\n \"path\": \"/build/11111111111111111\",\n \"requestId\": \"wk2t89y2ujo35ojs\",\n \"reason\": \"invalid_vin\",\n \"retryable\": false\n }\n}\n```\n\n### VIN Not in Coverage\n\nA non-North-American VIN, or a motorcycle, trailer or heavy truck, that no decoder named. `error.detectedMarket` or `error.detectedClass` says which. When a decoder names the car, the same VIN answers a 207 with `catalog: null`.\n\n```json\n{\n \"build\": {\n \"error\": \"No build data available\",\n \"vin\": \"6FPFXXMX2FRD07902\"\n },\n \"reason\": \"market_not_covered\",\n \"retryable\": false,\n \"error\": {\n \"status\": 404,\n \"error\": \"This VIN appears to be a non-US vehicle. auto.dev currently has full coverage for US-market vehicles only.\",\n \"code\": \"VIN_NOT_IN_COVERAGE\",\n \"path\": \"/build/6FPFXXMX2FRD07902\",\n \"requestId\": \"4k12o1tsrzyb4rai\",\n \"detectedMarket\": { \"country\": \"AU\", \"region\": \"Oceania\" },\n \"reason\": \"market_not_covered\",\n \"retryable\": false\n }\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "open-recalls": "Get currently active and unresolved vehicle recall information from the National Highway Traffic Safety Administration (NHTSA) database. This API filters out completed, closed, or resolved recalls to show only those requiring immediate attention or repair action.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/openrecalls/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/openrecalls/1FMUK7DHXSGA27345\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve open recalls for | |\n| `recalls` | string | | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst openRecalls = await response.json()\nconsole.log(`Found ${openRecalls.data.length} open recalls requiring attention`)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345',\n headers=headers\n)\n\nopen_recalls = response.json()\nprint(f\"Found {len(open_recalls['data'])} open recalls requiring attention\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/openrecalls/1FMUK7DHXSGA27345',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$openRecalls = json_decode($response, true);\necho \"Found \" . count($openRecalls['data']) . \" open recalls requiring attention\\n\";\n?>\n```\n\n## Response Structure\n\n\n **What counts as an open recall.** `data` and `openRecalls` cover only open **NHTSA** recalls — the recalls NHTSA itself would report for the VIN. Some manufacturers additionally report voluntary campaigns (warranty extensions, customer-satisfaction programs) that were never filed with NHTSA as safety recalls. When present, those are returned separately in `manufacturerCampaigns` and are **never** counted in `openRecalls`, so the open-recall count stays aligned with NHTSA while still surfacing everything the manufacturer flagged.\n\n\n### Main Response\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle` | object | Decoded year, make, model, and VIN of the subject vehicle. | |\n| `data` | array | Open NHTSA safety recalls for this VIN — the recalls NHTSA itself would report as open. Every entry uses the full NHTSA catalog shape documented under Open Recall Record Fields. This is the authoritative open-recall list, regardless of which upstream source answered. | |\n| `status` | string | Human-readable summary of the open NHTSA recall count (e.g., \"3 Open Recalls\", \"No Open Recalls\"). Counts `data` only. | |\n| `openRecalls` | number | Number of open NHTSA safety recalls — always equals `data.length`. Manufacturer voluntary campaigns are not counted here (see `manufacturerCampaigns`). | |\n| `totalRecalls` | number | Total recall campaigns issued against this year/make/model (includes recalls already remedied for this VIN). | |\n| `manufacturerCampaigns` | array | Open manufacturer voluntary campaigns — warranty extensions, customer-satisfaction programs, and other OEM actions the manufacturer reports but has not filed with NHTSA as safety recalls. Included so nothing the OEM flags is hidden, but kept out of `data` and never counted in `openRecalls`. Only present when the VIN has such campaigns. | |\n| `manufacturerCampaignCount` | number | Number of entries in `manufacturerCampaigns`. Only present when there is at least one. | |\n| `recalls` | | | |\n| `retrievedAt` | string | ISO 8601 timestamp of when the returned recall data was fetched from upstream. Recall data refreshes on a daily cycle, so this tells you how current the answer is. Null when the answer was not sourced from a cacheable upstream. | |\n| `examples` | object | Navigation links to related resources for exploration. | |\n\n### Open Recall Record Fields\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `manufacturer` | string | Vehicle manufacturer who issued the recall | |\n| `nhtsaCampaignNumber` | string | Unique NHTSA recall campaign identifier | |\n| `mfrCampaignNumber` | string | | |\n| `remedyAvailable` | boolean | Whether the dealer can perform the remedy right now. False when the manufacturer is still preparing the fix or parts are not yet at dealers; true when the remedy is in market and parts are available. | |\n| `parkIt` | boolean | Critical safety flag - vehicle should not be driven until repaired | |\n| `parkOutSide` | boolean | Critical safety flag - vehicle should be parked away from structures | |\n| `overTheAirUpdate` | boolean | Whether recall can be resolved via software update without dealer visit | |\n| `reportReceivedDate` | string | Date NHTSA received the recall report (DD/MM/YYYY format) | |\n| `component` | string | Vehicle component or system affected by the recall | |\n| `summary` | string | Detailed description of the recall issue and affected vehicles | |\n| `consequence` | string | Potential safety consequences if the recall is not addressed | |\n| `remedy` | string | Manufacturer instructions for resolving the recall issue | |\n| `notes` | string | null | Additional notes and contact information for vehicle owners, or null when the record has none | |\n| `mfrNotes` | string | Any additional notes the manufacturer provided | |\n| `isSafetyRecall` | boolean | Whether the record is a safety recall. A brand-new recall the manufacturer reports before NHTSA assigns a campaign number counts toward openRecalls when this is true. | |\n| `nhtsaActionNumber` | string | NHTSA action number for the recall, where NHTSA has assigned one | |\n| `modelYear` | string | Vehicle model year | |\n| `make` | string | Vehicle make (manufacturer) | |\n| `model` | string | Vehicle model name | |\n\n### Manufacturer Campaign Fields\n\nEntries in `manufacturerCampaigns` are open OEM campaigns that are **not** NHTSA safety recalls, so they carry no `nhtsaCampaignNumber` and none of the NHTSA-catalog-only fields (`component`, `parkIt`, `parkOutSide`, `overTheAirUpdate`). All fields are optional and reflect whatever the manufacturer supplied.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `mfrCampaignNumber` | string | Manufacturer\\ | |\n| `summary` | string | | |\n| `consequence` | string | What the manufacturer says can happen if the campaign is not addressed. Often absent for non-safety campaigns. | |\n| `remedy` | string | | |\n| `remedyAvailable` | boolean | Whether the dealer can perform the remedy now. | |\n| `reportReceivedDate` | string | Date the manufacturer opened the campaign. | |\n| `mfrNotes` | string | Any additional notes the manufacturer provided. | |\n\n## Example Response\n\nThe examples are illustrative: a VIN's answer changes as recalls are issued and remedied.\n\n### Vehicle with Open Recalls\n\n`data` holds only the open recalls. `openRecalls` is the count in `data`; `totalRecalls` is the full campaign history for the year/make/model and may be larger (it includes campaigns already remedied for this VIN).\n\n```json\n{\n \"vehicle\": { \"year\": 2025, \"make\": \"Ford\", \"model\": \"Explorer\", \"vin\": \"1FMUK7DHXSGA27345\" },\n \"data\": [\n {\n \"manufacturer\": \"Ford Motor Company\",\n \"nhtsaCampaignNumber\": \"25V239000\",\n \"mfrCampaignNumber\": \"25S35\",\n \"remedyAvailable\": true,\n \"parkIt\": false,\n \"parkOutSide\": false,\n \"overTheAirUpdate\": false,\n \"reportReceivedDate\": \"11/04/2025\",\n \"component\": \"POWER TRAIN:AUTOMATIC TRANSMISSION:CONTROL MODULE:SOFTWARE\",\n \"summary\": \"Ford Motor Company (Ford) is recalling certain 2025 Explorer vehicles. The powertrain control module (PCM) may reset while driving, which can damage the park system or cause an engine stall.\",\n \"consequence\": \"A damaged park system can result in a vehicle rollaway when the vehicle is placed in park without the parking brake applied. An engine stall while driving can result in a sudden loss of drive power. Either of these scenarios can increase the risk of a crash.\",\n \"remedy\": \"Dealers will update the powertrain control module software, free of charge. Owner notification letters were mailed June 6, 2025. Owners may contact Ford customer service at 1-866-436-7332. Ford's number for this recall is 25S35.\",\n \"notes\": \"Owners may also contact the National Highway Traffic Safety Administration Vehicle Safety Hotline at 888-327-4236 (TTY 888-275-9171) or go to nhtsa.gov.\",\n \"isSafetyRecall\": true,\n \"modelYear\": \"2025\",\n \"make\": \"FORD\",\n \"model\": \"EXPLORER\"\n }\n ],\n \"status\": \"1 Open Recall\",\n \"openRecalls\": 1,\n \"totalRecalls\": 3,\n \"manufacturerCampaigns\": [\n {\n \"mfrCampaignNumber\": \"25B12\",\n \"summary\": \"Customer Satisfaction Program: a front-camera calibration fault may affect certain 2025 Explorer vehicles. This is a manufacturer program, not a NHTSA safety recall, so it is listed here and not counted in openRecalls.\",\n \"remedy\": \"Dealers will recalibrate the front camera at no charge.\",\n \"remedyAvailable\": true,\n \"reportReceivedDate\": \"15/05/2025\"\n }\n ],\n \"manufacturerCampaignCount\": 1,\n \"retrievedAt\": \"2026-08-07T12:00:00.000Z\"\n}\n```\n\n### Vehicle with No Open Recalls\n\nWhen every recall for the VIN has been remedied, `data` is empty — while `totalRecalls` still reflects the full campaign history:\n\n```json\n{\n \"vehicle\": { \"year\": 2023, \"make\": \"Jeep\", \"model\": \"Compass\", \"vin\": \"3C4NJDBNXPT522408\" },\n \"data\": [],\n \"status\": \"No Open Recalls\",\n \"openRecalls\": 0,\n \"totalRecalls\": 2,\n \"retrievedAt\": \"2026-08-07T12:00:00.000Z\"\n}\n```\n\n### Full Recall Catalog (`?recalls=true`)\n\nAdd `?recalls=true` to also receive the complete make/model/year recall catalog — including already-remedied campaigns — in a separate `recalls` array. `data` still contains only open recalls. `recalls` lists each campaign once, and also holds any of the VIN's open recalls whose campaign the catalog does not list, so when no catalog is available it holds only those, and is an empty array if there are none. Catalog records use the field names documented under **Open Recall Record Fields** but carry only what the catalog supplies: the per-VIN fields `mfrCampaignNumber`, `remedyAvailable`, `mfrNotes` and `isSafetyRecall` are absent from them. An open recall added from `data` appears as it does there. A 2023 Jeep Compass with no open recalls:\n\n```json\n{\n \"vehicle\": { \"year\": 2023, \"make\": \"Jeep\", \"model\": \"Compass\", \"vin\": \"3C4NJDBNXPT522408\" },\n \"data\": [],\n \"status\": \"No Open Recalls\",\n \"openRecalls\": 0,\n \"totalRecalls\": 2,\n \"retrievedAt\": \"2026-08-07T12:00:00.000Z\",\n \"recalls\": [\n {\n \"manufacturer\": \"Chrysler (FCA US, LLC)\",\n \"nhtsaCampaignNumber\": \"23V576000\",\n \"parkIt\": false,\n \"parkOutSide\": false,\n \"overTheAirUpdate\": false,\n \"reportReceivedDate\": \"2023-08-14\",\n \"component\": \"ELECTRICAL SYSTEM: INSTRUMENT CLUSTER/PANEL\",\n \"summary\": \"Chrysler (FCA US, LLC) is recalling certain 2022-2023 Jeep Compass vehicles. The brightness level of the instrument panel cluster (IPC) may not be adjustable due to incorrect software in the body control module (BCM). As such, these vehicles fail to comply with the requirements of Federal Motor Vehicle Safety Standard number 101, \\\"Control and Displays.\\\"\",\n \"consequence\": \"An IPC display that is not bright enough may not clearly show critical safety information, such as the speedometer or warning lights, increasing the risk of a crash.\",\n \"remedy\": \"Dealers will update the body control module (BCM) software, free of charge. Owner notification letters were mailed August 29, 2023. Owners may contact FCA US, LLC customer service at 1-800-853-1403. FCA US, LLC's number for this recall is 88A.\",\n \"notes\": \"Owners may also contact the National Highway Traffic Safety Administration Vehicle Safety Hotline at 1-888-327-4236 (TTY 1-800-424-9153), or go to www.nhtsa.gov.\",\n \"modelYear\": \"2023\",\n \"make\": \"JEEP\",\n \"model\": \"COMPASS\"\n },\n {\n \"manufacturer\": \"Chrysler (FCA US, LLC)\",\n \"nhtsaCampaignNumber\": \"24V436000\",\n \"parkIt\": false,\n \"parkOutSide\": false,\n \"overTheAirUpdate\": true,\n \"reportReceivedDate\": \"2024-06-13\",\n \"component\": \"BACK OVER PREVENTION: SENSING SYSTEM: CAMERA\",\n \"summary\": \"Chrysler (FCA US, LLC) is recalling certain 2021-2022 Dodge Durango, 2021-2023 Chrysler Pacifica, Jeep Grand Cherokee L, 2022 Ram 1500, 2500, 3500, Chrysler Voyager, 2022-2023 Jeep Compass, Grand Cherokee, Wagoneer, Grand Wagoneer, and Ram Promaster vehicles. The radio software may prevent the rearview image from displaying. As such, these vehicles fail to comply with the requirements of Federal Motor Vehicle Safety Standard number 111, \\\"Rear Visibility.\\\"\",\n \"consequence\": \"A rearview camera image that does not display decreases the driver's visibility, increasing the risk of a crash.\",\n \"remedy\": \"Dealers will update the radio software or the software will be OTA, \\\"Over-The-Air,\\\" free of charge. Owner notification letters were mailed beginning July 9, 2024. Owners may contact FCA US, LLC customer service at 1-800-853-1403. FCA US, LLC's numbers for this recall are 66B and 79B.\",\n \"notes\": \"Owners may also contact the National Highway Traffic Safety Administration Vehicle Safety Hotline at 1-888-327-4236 (TTY 1-800-424-9153), or go to www.nhtsa.gov.\",\n \"modelYear\": \"2023\",\n \"make\": \"JEEP\",\n \"model\": \"COMPASS\"\n }\n ]\n}\n```\n\n> Every record, in `data` and in `recalls`, has the shape documented under **Open Recall Record Fields**. Fields a source did not supply are absent, and `notes` may be `null`.\n\n## Critical Safety Classifications\n\n### Immediate Action Required\n\n- **Park It** (`parkIt: true`) - **DO NOT DRIVE** - Vehicle poses immediate safety risk and should not be operated until repaired\n- **Park Outside** (`parkOutSide: true`) - **FIRE/EXPLOSION RISK** - Vehicle should be parked away from structures, garages, and other vehicles\n\n### Resolution Methods\n\n- **Over-the-Air Update** (`overTheAirUpdate: true`) - Can be resolved via software update without dealership visit\n- **Dealer Service Required** - Physical repair or part replacement needed at authorized service center\n\n### Recall Status Types\n\n- **Open** - Recall announced, remedy not yet available\n- **Remedy Available** - Fix is available, customer action required\n- **In Progress** - Customer has scheduled or begun remedy process\n\n## Use Cases\n\n- **Pre-Purchase Inspections**: Identify vehicles requiring immediate attention before sale\n- **Safety Alert Systems**: Notify owners of critical recalls requiring immediate action\n- **Fleet Management**: Prioritize vehicles needing urgent recall remediation\n- **Insurance Risk Assessment**: Evaluate vehicles with unresolved safety issues\n\n## Differences from Vehicle Recalls API\n\n| Feature | Vehicle Recalls API | Open Recalls API |\n| ----------------- | ------------------------ | ----------------------------------- |\n| **Scope** | All historical recalls | Only active/unresolved recalls |\n| **Use Case** | Complete recall history | Immediate action items |\n| **Status Filter** | All statuses | Open, In Progress, Remedy Available |\n| **Response Size** | Larger (historical data) | Smaller (active only) |\n\n## Error Responses\n\nErrors come wrapped in an `error` object. Every error response also carries the `api` and `user` blocks that successful responses have, omitted from the examples below.\n\n### Invalid VIN\n\nA malformed VIN answers 400 with code `INVALID_VIN_FORMAT`, and the response also carries the VIN as sent, `vinValid: false` and `examples` to try:\n\n```json\n{\n \"error\": {\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/openrecalls/1GYKPD\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n },\n \"vin\": \"1GYKPD\",\n \"vinValid\": false\n}\n```\n\nA well-formed VIN can also answer 400 with `VIN_CHECKSUM_FAILED` (\"Check digit failed: …\") or `VIN_DECODE_FAILED` (\"Unable to decode vehicle information from VIN\"). Those carry the `error` object only.\n\n### VIN Not Found\n\n```json\n{\n \"error\": {\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/openrecalls/1FTFW3LDXRFB40317\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n }\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "plate-to-vin": "Quickly decode any US license plate to get the VIN, year, make, model, and comprehensive vehicle information. This powerful API connects license plate data to detailed vehicle records across all 50 states.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/plate/{plateState}/{plateNumber}?state={state}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/plate/CA/ABC123\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `plate` | string | US license plate number to lookup | |\n| `state` | string | 2-letter state code where the plate is registered (e.g., CA, NY, TX) | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/plate/CA/ABC123\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/plate/CA/ABC123', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst plateData = await response.json()\nconsole.log(plateData.vehicle)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/plate/CA/ABC123',\n headers=headers\n)\n\nplate_data = response.json()\nprint(plate_data['vehicle'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/plate/CA/ABC123',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$plateData = json_decode($response, true);\nprint_r($plateData['vehicle']);\n?>\n```\n\n## Response Structure\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | Complete 17-character Vehicle Identification Number | |\n| `year` | number | Model year of the vehicle | |\n| `make` | string | Vehicle manufacturer name | |\n| `model` | string | Vehicle model name | |\n| `trim` | string | Complete trim designation | |\n| `drivetrain` | string | Vehicle drivetrain configuration | |\n| `engine` | string | Engine specification | |\n| `transmission` | string | Transmission type | |\n| `isDefault` | boolean | Whether this is the default configuration for the VIN | |\n\n## Example Response\n\n```json\n{\n \"vin\": \"1N4BL4BV3LC205823\",\n \"year\": 2020,\n \"make\": \"Nissan\",\n \"model\": \"Altima\",\n \"trim\": \"2.5 S Sedan 4D\",\n \"drivetrain\": \"FWD\",\n \"engine\": \"4-Cyl, 2.5 Liter\",\n \"transmission\": \"Automatic, Xtronic CVT\",\n \"isDefault\": true\n}\n```\n\n## State Coverage\n\nThe Plate-to-VIN API supports license plate lookups across all 50 US states with varying coverage levels by region.\n\n### Supported Plate Formats\n\n- **Standard plates**: ABC123, 123ABC, AB1234\n- **Vanity plates**: Custom personalized plates\n- **Commercial plates**: Truck, taxi, and fleet vehicles\n- **Special formats**: Plates with hyphens (AB-123) are automatically handled\n\n## Error Responses\n\n### Invalid License Plate\n\n```json\n{\n \"status\": 400,\n \"error\": \"License plate must be 2-8 alphanumeric characters\",\n \"code\": \"INVALID_PLATE_FORMAT\",\n \"path\": \"/plate/CA/ABC12345XYZ\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### Invalid State Code\n\n```json\n{\n \"status\": 400,\n \"error\": \"State must be a valid 2-letter US state code (e.g., CA, NY, TX)\",\n \"code\": \"INVALID_STATE_CODE\",\n \"path\": \"/plate/XX/ABC123\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\"\n}\n```\n\n### No Data Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"License plate found but no vehicle data available\",\n \"code\": \"NO_DATA_FOUND\",\n \"path\": \"/plate/CA/ABC123\",\n \"requestId\": \"d4e5f6g7h8i9j0k1\"\n}\n```\n\n### Plate Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle found for the provided license plate\",\n \"code\": \"PLATE_NOT_FOUND\",\n \"path\": \"/plate/CA/XYZ999\",\n \"requestId\": \"c3d4e5f6g7h8i9j0\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "specifications": "Get detailed vehicle specifications including engine details, features, measurements, colors, options, and complete technical data for any vehicle by VIN. Access comprehensive spec data organized by category for easy integration.\n\nA vehicle we can name but hold no full specifications for answers `207 Multi-Status`: the fields a source holds, `null` for every other documented field, and why. See [partial answers](#partial-answers-207).\n\n## Endpoint\n\n```\nGET https://api.auto.dev/specs/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/specs/1FTFW3LDXRFB40317\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number to retrieve specifications for | |\n| `ambiguity` | string | | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/specs/1FTFW3LDXRFB40317\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/specs/1FTFW3LDXRFB40317', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst specs = await response.json()\nconsole.log(specs.specs)\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/specs/1FTFW3LDXRFB40317',\n headers=headers\n)\n\nspecs = response.json()\nprint(specs['specs'])\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/specs/1FTFW3LDXRFB40317',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$specs = json_decode($response, true);\nprint_r($specs['specs']);\n?>\n```\n\n## Response Structure\n\n### Vehicle Information\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.manufacturer` | string | Full manufacturer name | |\n| `trims` | string[] | Present only when the VIN matches more than one style: every trim among them, most likely first. | |\n| `styles` | | | |\n| `candidates` | object[] | Deprecated: use `styles`. The same styles with their full specifications. | |\n\n### Basic Specifications\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.name` | string | Complete trim and specification name | |\n| `specs.totalSeating` | number | Total seating capacity | |\n| `specs.price.baseMsrp` | number | Manufacturer Suggested Retail Price | |\n| `specs.price.baseInvoice` | number | Dealer invoice price | |\n\n### Engine Specifications\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.engine.baseEngineSize` | string | Engine displacement (e.g., \"4.0 L\") | |\n| `specs.features.engine.cylinders` | string | Engine configuration (e.g., \"flat 6\") | |\n| `specs.features.engine.horsepower` | string | Engine horsepower rating with RPM | |\n| `specs.features.engine.torque` | string | Engine torque rating with RPM | |\n| `specs.features.engine.baseEngineType` | string | Fuel type (e.g., \"gas\") | |\n| `specs.features.engine.valves` | string | Number of valves | |\n| `specs.features.engine.camType` | string | Camshaft configuration | |\n| `specs.features.engine.valveTiming` | string | Valve timing type | |\n| `specs.features.engine.directInjection` | boolean | Direct injection availability | |\n\n### Measurements & Dimensions\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.measurements.length` | string | Overall vehicle length | |\n| `specs.features.measurements.height` | string | Overall vehicle height | |\n| `specs.features.measurements.wheelbase` | string | Wheelbase measurement | |\n| `specs.features.measurements.curbWeight` | string | Vehicle curb weight | |\n| `specs.features.measurements.grossWeight` | string | Gross vehicle weight | |\n| `specs.features.measurements.maximumPayload` | string | Maximum payload capacity | |\n| `specs.features.measurements.overallWidthWithMirrors` | string | Total width including mirrors | |\n| `specs.features.measurements.overallWidthWithoutMirrors` | string | Width excluding mirrors | |\n| `specs.features.measurements.manufacturer060MphAccelerationTime` | string | Manufacturer-rated 0-60 mph acceleration time | |\n| `specs.features.measurements.turningCircle` | string | Turning circle diameter | |\n| `specs.features.measurements.maximumCargoCapacity` | string | Maximum cargo capacity | |\n| `specs.features.measurements.countryOfFinalAssembly` | string | Country where vehicle was assembled | |\n\n### Fuel Economy\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.fuel.fuelType` | string | Required fuel type | |\n| `specs.features.fuel.epaCombinedMpg` | string | EPA combined MPG rating | |\n| `highwayMpg` | string | EPA city/highway MPG ratings | |\n| `specs.features.fuel.fuelTankCapacity` | string | Fuel tank capacity | |\n\n### Drive Train\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.driveTrain.driveType` | string | Drive wheel configuration (e.g., \"rear wheel drive\") | |\n| `specs.features.driveTrain.transmission` | string | Transmission type and configuration | |\n| `specs.features.driveTrain.rearLimitedSlipDifferential` | boolean | Rear limited slip differential availability | |\n| `specs.features.driveTrain.rearLockingDifferential` | boolean | Rear locking differential availability | |\n\n### Color Options\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.color.exterior` | array | Array of available exterior colors | |\n| `.name` | string | Color name | |\n| `.rgb` | string | RGB color values | |\n| `specs.color.interior` | array | Array of available interior colors | |\n| `.name` | string | Interior color/material name | |\n| `.rgb` | string | RGB color values | |\n\n### Additional Response Fields\n\n### Warranty Information\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.features.warranty.basic` | string | Basic warranty coverage | |\n| `specs.features.warranty.drivetrain` | string | Drivetrain warranty coverage | |\n| `specs.features.warranty.rust` | string | Corrosion/rust warranty | |\n| `specs.features.warranty.roadsideAssistance` | string | Roadside assistance coverage | |\n| `specs.features.warranty.freeMaintenance` | string | Free maintenance period | |\n\n### Ordered Features\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.orderedFeatures` | array | Array of feature categories with organized data | |\n| `.category` | string | Feature category name (e.g., \"Engine\", \"Safety\") | |\n| `.categoryGroup` | string | High-level grouping (e.g., \"Mechanical\", \"Interior\") | |\n| `.features` | object | Object containing category-specific features | |\n\n### Style Attributes\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `specs.styleAttributes.electric` | boolean | Whether vehicle is electric | |\n| `specs.styleAttributes.pluginElectric` | boolean | Whether vehicle is plug-in electric | |\n| `specs.styleAttributes.truck` | boolean | Whether vehicle is classified as a truck | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2019,\n \"make\": \"Porsche\",\n \"model\": \"911\",\n \"manufacturer\": \"Dr Ing HCF Porsch Ag\"\n },\n \"specs\": {\n \"name\": \"GT3 RS 2dr Coupe (4.0L 6cyl 7AM)\",\n \"price\": {\n \"baseMsrp\": 187500,\n \"baseInvoice\": 168750\n },\n \"totalSeating\": 2,\n \"color\": {\n \"exterior\": [\n {\n \"name\": \"Lizard Green\",\n \"rgb\": \"87,178,44\"\n },\n {\n \"name\": \"Miami Blue\",\n \"rgb\": \"3,161,192\"\n },\n {\n \"name\": \"Racing Yellow\",\n \"rgb\": \"229,200,38\"\n },\n {\n \"name\": \"Guards Red\",\n \"rgb\": \"175,26,28\"\n }\n ],\n \"interior\": [\n {\n \"name\": \"Black, leather/sueded microfiber\",\n \"rgb\": \"0,0,0\"\n },\n {\n \"name\": \"Black/Lizard Green, leather/sueded microfiber\",\n \"rgb\": \"0,0,0\"\n }\n ]\n },\n \"features\": {\n \"engine\": {\n \"torque\": \"346 lb-ft @ 6000 rpm\",\n \"baseEngineSize\": \"4.0 L\",\n \"horsepower\": \"520 hp @ 8250 rpm\",\n \"valves\": \"24\",\n \"baseEngineType\": \"gas\",\n \"directInjection\": true,\n \"valveTiming\": \"Variable\",\n \"cylinders\": \"flat 6\",\n \"camType\": \"Double overhead cam (DOHC)\"\n },\n \"fuel\": {\n \"epaCombinedMpg\": \"16 MPG\",\n \"epaCity/highwayMpg\": \"15/19 MPG\",\n \"rangeInMiles (city/hwy)\": \"253.5/321.1 mi.\",\n \"fuelTankCapacity\": \"16.9 gal.\",\n \"fuelType\": \"premium unleaded (required)\"\n },\n \"measurements\": {\n \"maximumCargoCapacity\": \"4.4 cu.ft.\",\n \"countryOfFinalAssembly\": \"Germany\",\n \"wheelbase\": \"96.6 in.\",\n \"curbWeight\": \"3153 lbs.\",\n \"grossWeight\": \"3953 lbs.\",\n \"cargoCapacity,AllSeatsInPlace\": \"4.4 cu.ft.\",\n \"maximumPayload\": \"800 lbs.\",\n \"overallWidthWithMirrors\": \"77.9 in.\",\n \"length\": \"179.4 in.\",\n \"manufacturer060MphAccelerationTime\": \"3.0 seconds\",\n \"turningCircle\": \"36.4 ft.\",\n \"height\": \"51.1 in.\",\n \"overallWidthWithoutMirrors\": \"74.0 in.\"\n },\n \"driveTrain\": {\n \"driveType\": \"rear wheel drive\",\n \"rearLockingDifferential\": true,\n \"rearLimitedSlipDifferential\": true,\n \"transmission\": \"7-speed automated manual\"\n },\n \"warranty\": {\n \"basic\": \"4 yr./ 50000 mi.\",\n \"drivetrain\": \"4 yr./ 50000 mi.\",\n \"freeMaintenance\": \"1 yr./ 10000 mi.\",\n \"rust\": \"12 yr./ unlimited mi.\",\n \"roadsideAssistance\": \"4 yr./ 50000 mi.\"\n },\n \"safety\": {\n \"4WheelAbs\": true,\n \"daytimeRunningLights\": true,\n \"engineImmobilizer\": true,\n \"postCollisionSafetySystem\": true,\n \"frontHeadAirbags\": true,\n \"dualFrontSideMountedAirbags\": true,\n \"passengerAirbagOccupantSensingDeactivation\": true,\n \"stabilityControl\": true,\n \"tirePressureMonitoring\": true,\n \"tractionControl\": true\n },\n \"frontseats\": {\n \"heightAdjustablePassengerSeat\": true,\n \"heightAdjustableDriverSeat\": true,\n \"sportFrontSeats\": true,\n \"2WayPowerPassengerSeat\": true,\n \"leather/suededMicrofiber\": true,\n \"2WayPowerDriverSeat\": true\n }\n },\n \"orderedFeatures\": [\n {\n \"category\": \"Fuel\",\n \"categoryGroup\": \"Mechanical\",\n \"features\": {\n \"fuelType\": \"Premium unleaded (required)\",\n \"epaCity/highwayMpg\": \"15/19 MPG\",\n \"epaCombinedMpg\": \"16 MPG\",\n \"rangeInMiles (city/hwy)\": \"253.5/321.1 mi.\",\n \"fuelTankCapacity\": \"16.9 gal.\"\n }\n },\n {\n \"category\": \"Engine\",\n \"categoryGroup\": \"Mechanical\",\n \"features\": {\n \"baseEngineSize\": \"4.0 L\",\n \"cylinders\": \"Flat 6\",\n \"baseEngineType\": \"Gas\",\n \"horsepower\": \"520 hp @ 8250 rpm\",\n \"torque\": \"346 lb-ft @ 6000 rpm\",\n \"valves\": \"24\",\n \"camType\": \"Double overhead cam (DOHC)\",\n \"valveTiming\": \"Variable\",\n \"directInjection\": true\n }\n }\n ],\n \"typeCategories\": {\n \"performancesports\": {\n \"id\": 10,\n \"name\": \"Performance/Sports\"\n },\n \"coupe\": {\n \"id\": 2,\n \"name\": \"Coupe\"\n },\n \"luxury\": {\n \"id\": 8,\n \"name\": \"Luxury\"\n }\n },\n \"styleAttributes\": {\n \"electric\": false,\n \"pluginElectric\": false,\n \"truck\": false\n }\n }\n}\n```\n\n## Feature Categories\n\nThe API returns comprehensive feature data organized into the following categories through the `orderedFeatures` array:\n\n### Mechanical Systems\n\n**Engine**:\n\n- Engine displacement, configuration, and type\n- Horsepower and torque ratings with RPM\n- Valve configuration and timing systems\n- Direct injection and fuel delivery\n\n**Drive Train**:\n\n- Transmission type and gear count\n- Drive wheel configuration (FWD, RWD, AWD, 4WD)\n- Differential options (limited slip, locking)\n- Transfer case specifications\n\n**Fuel**:\n\n- Fuel type requirements (regular, premium, etc.)\n- EPA city, highway, and combined MPG ratings\n- Fuel tank capacity and estimated range\n- Fuel system specifications\n\n**Suspension**:\n\n- Front and rear suspension types\n- Stabilizer bar configurations\n- Performance suspension options\n\n### Exterior Features\n\n**Measurements**:\n\n- Overall dimensions (length, width, height)\n- Wheelbase and track measurements\n- Weight specifications (curb, gross, payload)\n- Performance metrics (0-60 acceleration)\n- Cargo and storage capacities\n\n**Tires and Wheels**:\n\n- Wheel sizes and materials\n- Tire specifications and performance ratings\n- Available wheel finishes and options\n\n**Exterior Options**:\n\n- Lighting packages and LED systems\n- Body kit and aerodynamic elements\n- Mirror and trim options\n- Paint and finish selections\n\n### Interior Features\n\n**Seating**:\n\n- Seating capacity and configurations\n- Seat materials and adjustability options\n- Heating, cooling, and massage features\n- Memory and power adjustments\n\n**Comfort & Convenience**:\n\n- Climate control systems (single/dual zone)\n- Infotainment and connectivity features\n- Storage compartments and cup holders\n- Power accessories and convenience features\n\n**Interior Options**:\n\n- Premium material selections\n- Color and trim combinations\n- Ambient lighting packages\n- Technology and luxury upgrades\n\n### Safety & Security\n\n**Active Safety**:\n\n- Collision avoidance and mitigation systems\n- Driver assistance technologies\n- Stability and traction control systems\n- Emergency braking and steering assist\n\n**Passive Safety**:\n\n- Airbag systems and configurations\n- Structural safety reinforcements\n- Child safety systems and LATCH\n- Security and anti-theft systems\n\n**Safety & Security Options**:\n\n- Advanced driver assistance packages\n- Security system upgrades\n- Emergency response features\n\n### Technology & Entertainment\n\n**In Car Entertainment**:\n\n- Audio system specifications and speakers\n- Infotainment display and interface\n- Smartphone integration (Apple CarPlay, Android Auto)\n- Navigation and mapping systems\n- Satellite radio and streaming services\n\n**Telematics**:\n\n- Connected services and remote access\n- Vehicle tracking and stolen vehicle assistance\n- Over-the-air update capabilities\n- Emergency and concierge services\n\n### Packages & Options\n\n**Packages**:\n\n- Manufacturer option packages\n- Performance and appearance packages\n- Luxury and convenience bundles\n- Special edition and delivery options\n\n**Mechanical Options**:\n\n- Performance upgrades and modifications\n- Suspension and handling packages\n- Brake system upgrades\n- Powertrain enhancements\n\n## Use Cases\n\n- **Vehicle Comparison Tools**: Compare detailed specifications across multiple vehicles for purchase decisions with organized feature categories\n- **Automotive Marketplaces**: Display comprehensive vehicle features and specifications in listings with proper categorization\n- **Configuration Builders**: Help customers select vehicle options and packages based on available features and categories\n\n## Partial Answers (207)\n\nA `200` carries every documented `specs` field. When the sources hold only some of them for a vehicle we can name, `/specs` answers **`207 Multi-Status`**: `specs` with the fields a source holds, `null` for every other documented field, a `missing` list naming the null ones, and a `reason` that is a fact about the vehicle. A full answer stays a `200`; a VIN no decoder can name is the [404](#vin-not-found).\n\nA 2016 Harley-Davidson: vPIC, NHTSA's decoder, names it and gives its engine and fuel, but no catalog holds a motorcycle's price, colors, seating or feature list.\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1HD1BWV10GB016330\",\n \"year\": 2016,\n \"make\": \"HARLEY-DAVIDSON\",\n \"model\": \"FLSTC103 / Heritage Softail Classic\",\n \"manufacturer\": \"Harley-Davidson Motor Co\"\n },\n \"specs\": {\n \"name\": \"2016 HARLEY-DAVIDSON Heritage Softail Classic FLSTC103\",\n \"price\": null,\n \"totalSeating\": null,\n \"color\": null,\n \"typeCategories\": null,\n \"styleAttributes\": null,\n \"orderedFeatures\": null,\n \"features\": {\n \"engine\": {\n \"torque\": \"\",\n \"baseEngineSize\": \"1.69L\",\n \"horsepower\": \"\",\n \"valves\": \"\",\n \"baseEngineType\": \"Gasoline\",\n \"directInjection\": false,\n \"valveTiming\": \"\",\n \"cylinders\": \"2\",\n \"camType\": \"\"\n },\n \"fuel\": {\n \"epaCombinedMpg\": \"\",\n \"epaCityHighwayMpg\": \"\",\n \"rangeInMilesCityHwy\": \"\",\n \"fuelTankCapacity\": \"\",\n \"fuelType\": \"Gasoline\"\n },\n \"driveTrain\": {\n \"driveType\": \"\",\n \"centerLimitedSlipDifferential\": false,\n \"transmission\": \"\"\n },\n \"measurements\": {\n \"maximumCargoCapacity\": \"\",\n \"countryOfFinalAssembly\": \"UNITED STATES (USA)\",\n \"wheelbase\": \"\",\n \"curbWeight\": \"\",\n \"grossWeight\": \"Class 1A: 3,000 lb or less (1,360 kg or less)\",\n \"cargoCapacityAllSeatsInPlace\": \"\",\n \"maximumPayload\": \"\",\n \"length\": \"\",\n \"maximumTowingCapacity\": \"\",\n \"turningCircle\": \"\",\n \"height\": \"\",\n \"overallWidthWithoutMirrors\": \"\"\n },\n \"frontseats\": {\n \"frontHeadRoom\": \"\",\n \"premiumCloth\": false,\n \"bucketFrontSeats\": false,\n \"the4WayManualPassengerSeatAdjustment\": false,\n \"heightAdjustableDriverSeat\": false,\n \"frontShoulderRoom\": \"\",\n \"driverSeatWithPowerAdjustableLumbarSupport\": false,\n \"the8WayPowerDriverSeat\": false,\n \"frontLegRoom\": \"\",\n \"frontHipRoom\": \"\"\n },\n \"rearseats\": {},\n \"warranty\": {\n \"basic\": \"\",\n \"drivetrain\": \"\",\n \"freeMaintenance\": \"\",\n \"rust\": \"\",\n \"roadsideAssistance\": \"\"\n },\n \"suspension\": {},\n \"tiresAndWheels\": {},\n \"powerFeature\": {},\n \"mechanicalOptions\": {},\n \"comfortConvenience\": {},\n \"exteriorOptions\": {},\n \"interiorOptions\": {},\n \"instrumentation\": {\n \"clock\": false,\n \"compass\": false,\n \"externalTemperatureDisplay\": false,\n \"tripComputer\": false,\n \"tachometer\": false\n },\n \"inCarEntertainment\": {},\n \"packages\": {},\n \"telematics\": {},\n \"safety\": {}\n }\n },\n \"missing\": [\n { \"field\": \"price\", \"reason\": \"no_vin_record\" },\n { \"field\": \"totalSeating\", \"reason\": \"no_vin_record\" },\n { \"field\": \"color\", \"reason\": \"no_vin_record\" },\n { \"field\": \"typeCategories\", \"reason\": \"no_vin_record\" },\n { \"field\": \"styleAttributes\", \"reason\": \"no_vin_record\" },\n { \"field\": \"orderedFeatures\", \"reason\": \"no_vin_record\" }\n ],\n \"reason\": \"class_not_covered\",\n \"retryable\": false\n}\n```\n\nA 207 passes the `ok` check of most HTTP clients, and the fields in `missing` are `null`. Branch on the status, or check `missing`, before reading `specs`:\n\n```javascript tab=\"JavaScript\"\nconst res = await fetch(`https://api.auto.dev/specs/${vin}`, {\n headers: { Authorization: 'Bearer YOUR_API_KEY' },\n})\nconst data = await res.json()\n\nif (res.status === 207) {\n // data.specs holds what a source has; every field named in data.missing is null.\n // data.reason says why. It will not change: data.retryable is false.\n} else if (res.ok) {\n console.log(data.specs.price.baseMsrp)\n}\n```\n\n```python tab=\"Python\"\n\nres = requests.get(f'https://api.auto.dev/specs/{vin}', headers={'Authorization': 'Bearer YOUR_API_KEY'})\ndata = res.json()\n\nif res.status_code == 207:\n # data['specs'] holds what a source has; every field named in data['missing'] is None.\n # data['reason'] says why. It will not change: data['retryable'] is False.\n pass\nelif res.ok:\n print(data['specs']['price']['baseMsrp'])\n```\n\n### Response Structure (207)\n\n`vehicle` is the same as on a 200. `specs` has every documented top-level field: `name`, `price`, `totalSeating`, `color`, `typeCategories`, `styleAttributes`, `orderedFeatures` and `features`, each as on a 200 when a source holds it, `null` otherwise.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `.field` | string | A documented `specs` field that is `null` in this answer. | |\n| `.reason` | string | `no_vin_record`: no source holds this field for this VIN. | |\n| `reason` | string | Why the specifications are partial. One of the codes below. | |\n| `retryable` | boolean | Always `false` on `/specs`: asking again will not change the answer. | |\n\n### Reason Codes\n\nThe reason is about the vehicle when a fact about it says why; otherwise it is `no_vin_record`.\n\n| `reason` | means | retry |\n| -------------------- | ----------------------------------------------------------------------------------------------------------------- | ----- |\n| `class_not_covered` | a motorcycle, trailer, bus or other class the catalogs do not cover (an incomplete vehicle, a chassis cab, is covered) | no |\n| `market_not_covered` | a VIN built outside North America that vPIC does not decode | no |\n| `no_vin_record` | a covered vehicle no source holds a full record for (a 2026 Ford Mustang today, for one) | no |\n\nThe same `class_not_covered` and `market_not_covered` codes ride the `/vin` and `/build` partial answers. See [error responses](/v2/reference/errors#207-multi-status-is-not-an-error).\n\n### Billing\n\nA 207 is not a billed call and counts toward no quota.\n\n## Error Responses\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be 17 characters long\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/specs/123Invalid\",\n \"requestId\": \"966d9900bef4356c-IAD\"\n}\n```\n\n### VIN Not Found\n\nA 404 means no decoder could name the make of the vehicle. A vehicle whose make a decoder names, with specifications only in part, is a [207](#partial-answers-207).\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/specs/1FTFW3LDXRFB40317\",\n \"requestId\": \"f8g7h6i5j4k3l2m1\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "taxes-fees": "Retrieve comprehensive tax and fee calculations for vehicle sales transactions. This API provides accurate, location-specific tax rates and government fees, ensuring compliance with local regulations and transparent pricing for both dealers and consumers.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/taxes/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/taxes/19UDE2F31MA000428?zip=94020&price=25000&docFee=200\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | The Vehicle Identification Number (e.g. 19UDE2F31MA000428) | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `price` | number | The vehicle price (e.g., 25000). Defaults to 25000 if not provided. | |\n| `zip` | string | The ZIP code of the location (e.g. 94020). If not provided, defaults to user zipcode or 94020. | |\n| `docFee` | number | Documentation fee (e.g., 200). Defaults to 200 if not provided. | |\n| `tradeIn` | number | Trade-in value to deduct from taxable amount (e.g., 5000). Defaults to 0 if not provided. | |\n| `rate` | number | Interest rate for financing calculations (e.g., 9.99). Defaults to 9.99 if not provided. | |\n| `downPayment` | number | Down payment amount (e.g., 5000). Defaults to 0 if not provided. | |\n| `months` | number | Loan term in months (e.g., 72). Defaults to 72 if not provided. | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/taxes/19UDE2F31MA000428?zip=94020&price=25000&docFee=200\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n```javascript tab=\"JavaScript\"\nconst vin = '19UDE2F31MA000428'\nconst params = new URLSearchParams({\n zip: '94020',\n price: '25000',\n docFee: '200',\n rate: '9.99',\n})\n\nconst response = await fetch(`https://api.auto.dev/taxes/${vin}?${params}`, {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n },\n})\n\nconst taxData = await response.json()\nconsole.log(`Total: $${taxData.totalTaxesAndFees}`)\n```\n\n```python tab=\"Python\"\n\nvin = '19UDE2F31MA000428'\nparams = {\n 'zip': '94020',\n 'price': '25000',\n 'docFee': '200',\n 'rate': '9.99'\n}\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY'\n}\n\nresponse = requests.get(\n f'https://api.auto.dev/taxes/{vin}',\n headers=headers,\n params=params\n)\n\ntax_data = response.json()\nprint(f\"Total: ${tax_data['totalTaxesAndFees']}\")\n```\n\n```php tab=\"PHP\"\n '94020',\n 'price' => '25000',\n 'docFee' => '200',\n 'rate' => '9.99'\n]);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"https://api.auto.dev/taxes/{$vin}?{$params}\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY'\n ]\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$taxData = json_decode($response, true);\necho \"Total: $\" . $taxData['totalTaxesAndFees'];\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | string | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `criteria.price` | number | Vehicle sale price used for calculations | |\n| `criteria.zip` | string | ZIP code for tax jurisdiction lookup | |\n| `criteria.docFee` | number | Documentation fee included in calculation | |\n| `criteria.tradeIn` | string | Trade-in value deducted from taxable amount | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `totalTaxesAndFees` | number | Total amount of all taxes and fees combined | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `taxes.stateSalesTax` | number | State-level sales tax amount | |\n| `taxes.countySalesTax` | number | County-level sales tax amount | |\n| `taxes.citySalesTax` | number | City-level sales tax amount | |\n| `taxes.districtSalesTax` | number | Special district sales tax amount | |\n| `taxes.combinedSalesTax` | number | Total of all sales taxes | |\n| `taxes.gasGuzzlerTax` | number | Federal gas guzzler tax (if applicable) | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `fees.titleFee` | number | Vehicle title processing fee | |\n| `fees.registrationFee` | number | Vehicle registration fee | |\n| `fees.dmvFee` | number | Standard DMV processing fee | |\n| `fees.docFee` | number | Dealer documentation fee | |\n| `fees.combinedFees` | number | Total of all government fees | |\n| `fees.dmvFees` | object | Detailed breakdown of DMV-specific fees | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"19UDE2F31MA000428\",\n \"year\": 2021,\n \"make\": \"Acura\",\n \"model\": \"ILX\"\n },\n \"criteria\": {\n \"price\": \"85000\",\n \"zip\": \"90210\",\n \"docFee\": 200,\n \"tradeIn\": 0\n },\n \"totalTaxesAndFees\": 9585.5,\n \"taxes\": {\n \"citySalesTax\": 637.5,\n \"combinedSalesTax\": 8500,\n \"countySalesTax\": 212.5,\n \"districtSalesTax\": 2550,\n \"stateSalesTax\": 5100,\n \"gasGuzzlerTax\": 0\n },\n \"fees\": {\n \"titleFee\": 23,\n \"registrationFee\": 65,\n \"dmvFee\": 797.5,\n \"combinedFees\": 1085.5,\n \"docFee\": 200,\n \"dmvFees\": {\n \"Air Quality Fee\": 6,\n \"Alternative Fuel/Technology Fee\": 3,\n \"Auto theft deterrence/DUI fee\": 2,\n \"Fingerprint ID Fee\": 1,\n \"Highway Patrol Fee\": 29,\n \"Reflectorized license plate fee\": 1,\n \"Service Authority for Freeway Emergencies fee\": 1,\n \"Smog Abatement Fee\": 12,\n \"Transfer Fee\": 15,\n \"Transportation Improvement Fee\": 175,\n \"Vehicle License Fee\": 552.5\n }\n }\n}\n```\n\n## Use Cases\n\n- **Dealership Sales Calculator**: Build accurate \"out-the-door\" pricing for customers including all taxes and fees\n- **Multi-State Comparison**: Compare total registration costs across different states for purchase optimization\n- **Financing Integration**: Calculate accurate amounts to finance including all applicable taxes and fees\n\n## Error Responses\n\n### Invalid Request\n\n```json\n{\n \"status\": 400,\n \"error\": \"Oops! Something went wrong while fetching your taxes.\",\n \"code\": \"INVALID_REQUEST\",\n \"path\": \"/taxes/1FTFW3LDXRFB40317?zip=12345\",\n \"requestId\": \"b2c3d4e5f6g7h8i9\",\n \"suggestion\": \"Please check zip code: 12345\"\n}\n```\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters containing only letters and numbers (excluding I, O, Q)\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/taxes/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n### VIN Not Found\n\n```json\n{\n \"status\": 404,\n \"error\": \"No vehicle data found for the provided VIN\",\n \"code\": \"VIN_NOT_FOUND\",\n \"path\": \"/taxes/1FTFW3LDXRFB40317\",\n \"requestId\": \"c3d4e5f6g7h8i9j0\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ❌ Not available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "total-cost-ownership": "Calculate comprehensive Total Cost of Ownership (TCO) for any vehicle over a 5-year period. Get detailed breakdowns of all ownership costs including depreciation, fuel, maintenance, repairs, insurance, taxes, and financing.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/tco/{vin}\n```\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/tco/1FTFW3LDXRFB40317?zip=90210&milesPerYear=12000\n```\n\n## Parameters\n\n### Path Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | string | 17-character Vehicle Identification Number | |\n\n### Query Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `zip` | string | 5-digit ZIP code for location-based calculations (insurance, taxes, fees) | Auto-detected based on user location |\n| `fromZip` | string | 5-digit ZIP code for delivery/transport calculations | |\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/tco/1FTFW3LDXRFB40317?zip=76548&fromZip=60695\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst vin = '1FTFW3LDXRFB40317'\nconst params = new URLSearchParams({\n zip: '76548',\n fromZip: '60695',\n})\n\nconst response = await fetch(`https://api.auto.dev/tco/${vin}?${params}`, {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst tco = await response.json()\nconsole.log(`Total 5-year cost: $${tco.tco.total.tcoPrice}`)\nconsole.log(`Average cost per mile: $${tco.tco.total.averageCostPerMile}`)\n```\n\n```python tab=\"Python\"\n\nvin = '1FTFW3LDXRFB40317'\nparams = {\n 'zip': '76548',\n 'fromZip': '60695'\n}\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(f'https://api.auto.dev/tco/{vin}', params=params, headers=headers)\ntco = response.json()\nprint(f\"Total 5-year cost: ${tco['tco']['total']['tcoPrice']}\")\n```\n\n```php tab=\"PHP\"\n '76548',\n 'fromZip' => '60695'\n]);\n\n$curl = curl_init();\n\ncurl_setopt_array($curl, [\n CURLOPT_URL => \"https://api.auto.dev/tco/{$vin}?{$query}\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$tco = json_decode($response, true);\necho \"Total 5-year cost: $\" . $tco['tco']['total']['tcoPrice'] . \"\\n\";\n?>\n```\n\n## Response Structure\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.vin` | string | Vehicle Identification Number | |\n| `vehicle.year` | number | Model year | |\n| `vehicle.make` | string | Vehicle manufacturer | |\n| `vehicle.model` | string | Vehicle model name | |\n| `vehicle.manufacturer` | string | Full manufacturer name | |\n| `zip` | string | ZIP code used for location-based calculations | |\n| `styleId` | string | Present only when the VIN matches more than one style: the style these costs are for. | |\n| `trims` | string[] | Present only when the VIN matches more than one style: every trim among them, most likely first. | |\n| `styles` | | | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `tco.total.federalTaxCredit` | number | Federal tax credits available (electric vehicles) | |\n| `tco.total.insurance` | number | Total insurance costs over 5 years | |\n| `tco.total.maintenance` | number | Total maintenance costs over 5 years | |\n| `tco.total.repairs` | number | Total repair costs over 5 years | |\n| `tco.total.taxesAndFees` | number | Total taxes and fees over 5 years | |\n| `tco.total.financeInterest` | number | Total financing interest over 5 years | |\n| `tco.total.depreciation` | number | Total depreciation over 5 years | |\n| `tco.total.fuel` | number | Total fuel costs over 5 years | |\n| `tco.total.tcoPrice` | number | Total cost of ownership over 5 years | |\n| `tco.total.averageCostPerMile` | number | Average cost per mile over 5 years | |\n\n\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `.insurance` | number | Insurance costs for the year | |\n| `.maintenance` | number | Maintenance costs for the year | |\n| `.repairs` | number | Repair costs for the year | |\n| `.taxesAndFees` | number | Taxes and fees for the year | |\n| `.financeInterest` | number | Financing interest for the year | |\n| `.depreciation` | number | Depreciation for the year | |\n| `.fuel` | number | Fuel costs for the year | |\n| `.tcoPrice` | number | Total cost for the year | |\n| `.averageCostPerMile` | number | Average cost per mile for the year | |\n\n## Example Response\n\n```json\n{\n \"vehicle\": {\n \"vin\": \"1FTFW3LDXRFB40317\",\n \"year\": 2019,\n \"make\": \"Porsche\",\n \"model\": \"911\",\n \"manufacturer\": \"Dr Ing HCF Porsch Ag\"\n },\n \"zip\": \"90210\",\n \"tco\": {\n \"total\": {\n \"federalTaxCredit\": 0,\n \"insurance\": 12110,\n \"maintenance\": 13788,\n \"repairs\": 11874,\n \"taxesAndFees\": 12164,\n \"financeInterest\": 20657,\n \"depreciation\": 44236,\n \"fuel\": 25000,\n \"tcoPrice\": 139829,\n \"averageCostPerMile\": 1.86\n },\n \"years\": {\n \"1\": {\n \"insurance\": 2281,\n \"maintenance\": 2006,\n \"repairs\": 2038,\n \"taxesAndFees\": 9728,\n \"financeInterest\": 7077,\n \"depreciation\": 13474,\n \"fuel\": 4709,\n \"tcoPrice\": 41313,\n \"averageCostPerMile\": 1.86\n },\n \"2\": {\n \"insurance\": 2349,\n \"maintenance\": 147,\n \"repairs\": 2195,\n \"taxesAndFees\": 684,\n \"financeInterest\": 5710,\n \"depreciation\": 7566,\n \"fuel\": 4850,\n \"tcoPrice\": 23501,\n \"averageCostPerMile\": 1.86\n },\n \"3\": {\n \"insurance\": 2420,\n \"maintenance\": 6898,\n \"repairs\": 2364,\n \"taxesAndFees\": 635,\n \"financeInterest\": 4241,\n \"depreciation\": 8510,\n \"fuel\": 4996,\n \"tcoPrice\": 30064,\n \"averageCostPerMile\": 1.86\n },\n \"4\": {\n \"insurance\": 2493,\n \"maintenance\": 694,\n \"repairs\": 2543,\n \"taxesAndFees\": 579,\n \"financeInterest\": 2663,\n \"depreciation\": 6296,\n \"fuel\": 5145,\n \"tcoPrice\": 20413,\n \"averageCostPerMile\": 1.86\n },\n \"5\": {\n \"insurance\": 2567,\n \"maintenance\": 4043,\n \"repairs\": 2734,\n \"taxesAndFees\": 538,\n \"financeInterest\": 966,\n \"depreciation\": 8390,\n \"fuel\": 5300,\n \"tcoPrice\": 24538,\n \"averageCostPerMile\": 1.86\n }\n }\n }\n}\n```\n\n## Cost Component Analysis\n\nThe TCO calculation includes five main cost components:\n\n- **Depreciation** - Vehicle value loss over time (largest cost factor)\n- **Fuel Costs** - Based on EPA ratings and local fuel prices\n- **Financing Interest** - Loan interest payments over ownership period\n- **Insurance** - Annual insurance premiums based on vehicle and location\n- **Maintenance & Repairs** - Scheduled maintenance and expected repairs\n\n## Use Cases\n\n- **Vehicle Purchase Decisions**: Compare total ownership costs between different vehicles before buying\n- **Fleet Management**: Evaluate long-term costs for fleet vehicle selection and budget planning\n- **Lease vs Buy Analysis**: Calculate comprehensive costs to determine optimal vehicle acquisition strategy\n\n## Error Responses\n\n### Invalid Location\n\n```json\n{\n \"status\": 400,\n \"error\": \"Invalid ZIP code format. ZIP code must be 5 digits (e.g., 90210) or 5+4 format (e.g., 90210-1234)\",\n \"code\": \"INVALID_LOCATION\",\n \"path\": \"/tco/1GYKPDRSXSZ102995?zip=ABCDE\",\n \"requestId\": \"d4e5f6g7h8i9j0k1\"\n}\n```\n\n### Invalid VIN\n\n```json\n{\n \"status\": 400,\n \"error\": \"VIN must be exactly 17 characters\",\n \"code\": \"INVALID_VIN_FORMAT\",\n \"path\": \"/tco/123Invalid\",\n \"requestId\": \"a1b2c3d4e5f6g7h8\"\n}\n```\n\n## Interactive API Reference\n\nReady to test this endpoint? Use our interactive API playground to make live requests and see real responses.\n\n## Plan Availability\n\n- **Free**: ❌ Not available\n- **Growth**: ✅ Available\n- **Scale**: ✅ Available\n\nSee [pricing](https://auto.dev/pricing) for plan details and signup.\n", + "vehicle-listings": "Get comprehensive vehicle listings from U.S. physical & online dealers in seconds. Our Vehicle Listings API provides detailed vehicle information, dealership data, specifications, and market pricing.\n\n## Endpoint\n\n```\nGET https://api.auto.dev/listings\nGET https://api.auto.dev/listings/{vin}\n```\n\nReturns vehicle listings. Without a VIN, returns an array of listings (typically 100 per page). With a VIN, returns a single specific listing.\n\n## View in Browser\n\n```http\nhttps://api.auto.dev/listings\n```\n\n## Parameters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vin` | | | |\n| `includeUnpriced` | boolean | Opt in to listings with `retailListing.price = null`. Off by default; zero/null-price rows are filtered out unless this is set to `true`. | false |\n\n## Pagination\n\nPagination is supported for large result sets.\n\nUse the `page` parameter to navigate through the results. For example, `page=2` will return the second page of results.\n\nLimit the number of results per page using the `limit` parameter. For example, `limit=10` will return 10 results per page.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `page` | number | Page number to retrieve (starting from 1) | 1 |\n| `limit` | number | Number of listings to return per page. Maximum varies by plan — see \"Per-plan limit caps\" below. | 100 |\n\n```http\nhttps://api.auto.dev/listings?page=2&limit=50\n```\n\n### Cursor pagination (recommended for deep browsing)\n\nFor page 50 and beyond, the API auto-issues a cursor in `links.next`:\n\n```json\n{\n \"data\": [...],\n \"links\": {\n \"self\": \"/listings?page=50&limit=20\",\n \"next\": \"/listings?cursor=eyJrIjoxNzMyMDg...&limit=20\",\n \"prev\": \"/listings?page=49&limit=20\",\n \"first\": \"/listings\",\n \"last\": \"/listings?page=...&limit=20\"\n }\n}\n```\n\nFollow `links.next` — it stays fast at any depth, while `?page=N` past 100 gets slower.\n\nOnce a request includes `?cursor=`, the response returns `self`, `next`, `prev`, and `first` (no `last`). Follow `first` to jump back to the start.\n\nCursor tokens are opaque — don't parse or modify them, and don't reuse them across sort changes. A cursor issued under one sort returns 400 under another; drop `?cursor=` and re-paginate.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `cursor` | string | Opaque pagination token issued by the API in links.next at page 50+. Follow the link rather than constructing manually. | |\n\n### Per-plan `?limit=` caps\n\n`?limit=` is capped per plan. Requests above your plan's cap silently clamp to the cap — no 400 is returned, pages just come back smaller.\n\n| Plan | Max `?limit=` |\n| ------- | ------------- |\n| Free | 20 |\n| Growth | 100 |\n| Scale | 500 |\n\n## Sorting\n\nSort results using the `sort` parameter. Pass a field name followed by an optional direction (`asc` or `desc`). Default direction is `asc`. Default sort when no `?sort=` is provided is `updatedAt.desc` (most recently updated first).\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `sort` | string | Sort field with optional direction. Format: or .. Single field only — multi-column sort is not supported. | updatedAt.desc |\n\n### Supported sort fields\n\n| Field | Description |\n| ----------- | ---------------------------------------------------------- |\n| `createdAt` | When the listing was first added |\n| `updatedAt` | When the listing was last updated (default) |\n| `price` | Retail price |\n| `miles` | Vehicle mileage (`mileage` is an accepted alias) |\n| `year` | Model year |\n\n`distance` is not supported as a sort. `random` is not supported on `/listings` (each page would reshuffle, making pagination meaningless). Multi-column sort is not supported — pass a single field only.\n\n### Examples\n\n```http\nhttps://api.auto.dev/listings?sort=price.asc\n```\n\n```http\nhttps://api.auto.dev/listings?sort=year.desc&vehicle.make=Toyota\n```\n\n## Field Selection\n\nProject the response down to only the fields you need with `?select=`. Pass a comma-separated list of field paths. Any field not listed is omitted from each result, which yields smaller payloads and lower latency.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `select` | string | Comma-separated list of field paths to project, e.g. `vehicle.vin,vehicle.year,vehicle.make,retailListing.price`. Nested fields require dot notation (`vehicle.vin`, not `vin` — the top-level `vin` is a convenience mirror in the default response, not a valid select path). Top-level fields that have no nested equivalent — `createdAt`, `updatedAt`, `location` — use their bare name. Omit to receive the full default response. | |\n\n```http\nhttps://api.auto.dev/listings?select=vehicle.vin,vehicle.year,vehicle.make,retailListing.price&limit=1\n```\n\n**Important:** when `?select=` is used, `data[]` rows come back with **flat dot-keyed properties** rather than the nested objects of the default response. Compare (showing `vehicle.vin` in both for symmetry):\n\n```json\n// Default response — nested\n{\n \"vehicle\": {\n \"vin\": \"YV4L12UC0S2574760\",\n \"year\": 2025,\n \"make\": \"Volvo\",\n ...\n },\n \"retailListing\": { \"price\": 30975, ... }\n}\n\n// With ?select=vehicle.vin,vehicle.year,vehicle.make,retailListing.price\n{\n \"vehicle.vin\": \"YV4L12UC0S2574760\",\n \"vehicle.year\": 2025,\n \"vehicle.make\": \"Volvo\",\n \"retailListing.price\": 30975\n}\n```\n\nThe default response also surfaces a top-level `vin` that mirrors `vehicle.vin` for convenience, but it is **not** a valid `?select=` path — use `vehicle.vin` instead. Other top-level fields with no nested equivalent (`createdAt`, `updatedAt`, `location`) are selectable by their bare name.\n\nClients that traverse the response by key path need to handle both shapes when toggling `?select=` on and off.\n\n## Location Filtering\n\nFilter listings by geographic location using the `zip` and `distance` parameters.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `zip` | string | 5-digit ZIP code to center the search around | |\n| `distance` | number | Radius in miles from the ZIP code to include in results | 50 |\n\n```http\nhttps://api.auto.dev/listings?zip=33132&distance=50\n```\n\n## Search Listings\n\nSimply make a GET request to listings with your desired search parameters. You can filter by make, model, year, price, mileage, and more. Use commas to specify multiple values.\n\n```http\nhttps://api.auto.dev/listings?vehicle.make=ford&vehicle.model=mustang\n```\n\n### Filter syntax\n\nAll filter parameters share the same operator vocabulary:\n\n- **Comma for multiple values** — `vehicle.make=Ford,Chevrolet` (logical OR).\n- **Dash for numeric ranges** — `retailListing.price=10000-30000` or `vehicle.year=2018-2024`. Ranges are inclusive on both ends.\n\nThese combine: `vehicle.year=2018-2024&vehicle.make=Ford,Chevrolet&retailListing.cpo=true` is valid and behaves as expected.\n\n### Vehicle Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `vehicle.squishVin` | string | 10-character squish VIN — positions 1-8 + 10-11 of the full VIN. Drops the check digit (position 9) and the per-vehicle production sequence (positions 12-17), so it identifies the VIN configuration (make/model/year/plant) — multiple distinct vehicles can share the same squish. Use comma for multiple: 1FA6P8AMF5,137FA5733E | |\n| `vehicle.year` | number | The year of the vehicle. Use specific year (2018) or range (2018-2020) | |\n| `vehicle.make` | string | Vehicle manufacturer. Use comma for multiple: Ford,Chevrolet | |\n| `vehicle.model` | string | Vehicle model. Use comma for multiple: F-150,Silverado | |\n| `vehicle.trim` | string | Trim level. Use comma for multiple: XLT,LT | |\n| `vehicle.bodyStyle` | string | Body style. Use comma for multiple: sedan,coupe | |\n| `vehicle.engine` | string | Engine size. Use comma for multiple: 2.0L,3.5L | |\n| `vehicle.fuel` | string | Fuel type. Use comma for multiple: Gasoline,Hybrid,Electric,Plug-In Hybrid,Diesel | |\n| `vehicle.transmission` | string | Transmission type. Use comma for multiple: automatic,manual | |\n| `vehicle.interiorColor` | string | Interior color. Use comma for multiple: black,gray | |\n| `vehicle.exteriorColor` | string | Exterior color. Use comma for multiple: white,black | |\n| `vehicle.doors` | number | Number of doors (2, 4, 5) | |\n\n### Retail Listing Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `retailListing.price` | number | Vehicle price. Use range: 10000-20000 | |\n| `retailListing.state` | string | State where vehicle is located (e.g., CA) | |\n| `retailListing.miles` | number | Vehicle mileage. Use range: 10000-20000 | |\n| `retailListing.used` | boolean | Used vs new. `true` for used vehicles, `false` for new. | |\n| `retailListing.cpo` | boolean | Certified Pre-Owned flag. `true` filters to CPO listings. | |\n\n### Dealer Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `dealerId` | string | Dealer ID as returned in `retailListing.dealerId`. Filter by it to return all listings for that dealer. Use comma for multiple. | |\n| `dealerZip` | string | ZIP code(s) the dealer is located in. Distinct from the top-level `zip` parameter (buyer-center for radius search). Use comma for multiple. | |\n\n### Wholesale Listing Filters\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `wholesaleListing.buyNowPrice` | number | Wholesale buy now price. Use range: 10000-20000 | |\n| `wholesaleListing.state` | string | State where vehicle is located (e.g., CA) | |\n| `wholesaleListing.miles` | number | Vehicle mileage. Use range: 10000-20000 | |\n\nFor example, to find Toyota Camrys under $30k in California:\n\n```http\nhttps://api.auto.dev/listings?vehicle.make=Toyota&vehicle.model=Camry&retailListing.price=1-30000&retailListing.state=CA\n```\n\n## Example Request\n\n```bash tab=\"curl\"\ncurl -X GET \"https://api.auto.dev/listings/10ARJYBS7RC154562\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\"\n```\n\n```javascript tab=\"JavaScript\"\nconst response = await fetch('https://api.auto.dev/listings/10ARJYBS7RC154562', {\n headers: {\n Authorization: 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json',\n },\n})\n\nconst result = await response.json()\nconst listings = result.data\nconsole.log(`Found ${listings.length} listings`)\nlistings.forEach((listing) => {\n console.log(\n `${listing.vehicle.year} ${listing.vehicle.make} ${listing.vehicle.model} - $${listing.retailListing?.price || 0}`,\n )\n})\n```\n\n```python tab=\"Python\"\n\nheaders = {\n 'Authorization': 'Bearer YOUR_API_KEY',\n 'Content-Type': 'application/json'\n}\n\nresponse = requests.get(\n 'https://api.auto.dev/listings/10ARJYBS7RC154562',\n headers=headers\n)\n\nresult = response.json()\nfor listing in result['data']:\n vehicle = listing['vehicle']\n price = listing['retailListing']['price'] if listing['retailListing'] else 0\n print(f\"{vehicle['year']} {vehicle['make']} {vehicle['model']} - ${price}\")\n```\n\n```php tab=\"PHP\"\n 'https://api.auto.dev/listings/10ARJYBS7RC154562',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer YOUR_API_KEY',\n 'Content-Type: application/json'\n ],\n]);\n\n$response = curl_exec($curl);\ncurl_close($curl);\n\n$result = json_decode($response, true);\nforeach ($result['data'] as $listing) {\n $vehicle = $listing['vehicle'];\n $price = $listing['retailListing']['price'] ?? 0;\n echo \"{$vehicle['year']} {$vehicle['make']} {$vehicle['model']} - \\${$price}\\n\";\n}\n?>\n```\n\n## Response Structure\n\n### Response Envelope\n\nBoth endpoints return a wrapper object:\n\n```json\n{\n \"data\": ...,\n \"links\": { \"self\": \"...\", \"next\": \"...\", \"prev\": \"...\", \"first\": \"...\", \"last\": \"...\" },\n \"total\": 12345\n}\n```\n\n- **`data`** — the payload. Array of listing objects for `/listings`, a single listing object for `/listings/{vin}`.\n For a vehicle with no current listing, `/listings/{vin}` answers with its most recent stored listing, in the same\n shape, plus `removedAt`: the last time a source saw it listed. The vehicle left the market within 48 hours after.\n With nothing stored, the answer is a 404.\n- **`links`** — pagination URLs on array responses. See the accordion below for shape and behavior in cursor mode.\n- **`total`** — present only when `?includes=total` is passed. Count of matching rows ignoring pagination.\n\n### Pagination links (`links`)\n\n`/listings` array responses include a `links` object. The full set of fields is emitted in **page mode** (default — `?page=` or no pagination param). Once the request is in **cursor mode** (includes `?cursor=`), `last` is omitted.\n\n| Parameter | Type | Description | Default |\n|-----------|------|-------------|--------|\n| `links.self` | string | URL of the current page request | |\n| `links.next` | string | URL of the next page. At page 50+, switches from ?page= to ?cursor=. Absent on the final page. | |\n| `links.prev` | string | URL of the previous page. Absent on the first page. | |\n| `links.first` | string | URL of the first page (the base /listings URL with current filters and sort) | |\n| `links.last` | string | URL of the final page. Omitted when the request is already in cursor mode. | |\n| `links.toggleFacets` | string | URL that flips the `?includes=` parameter to toggle facets off (or on, if currently off). Convenience for UIs that show a \"show/hide facets\" affordance. | |\n| `links.toggleTotal` | string | URL that flips the `?includes=` parameter to toggle total off (or on, if currently off). | |\n\n### Total count (`total`)\n\nAdd `?includes=total` to receive a `total` field with the count of matching rows ignoring pagination.\n\n```http\nhttps://api.auto.dev/listings?vehicle.make=Ford&includes=total\n```\n\n```json\n{\n \"data\": [...],\n \"links\": {...},\n \"total\": 87432\n}\n```\n\n### Facets (`facets`)\n\nAdd `?includes=facets` to receive a `facets` field with bucketed counts and ready-to-use drill-down URLs for each filterable dimension, ignoring pagination. Use this to power refinement UIs (e.g. \"Filter by make\" sidebar).\n\n```http\nhttps://api.auto.dev/listings?vehicle.year=2020-2024&includes=facets\n```\n\nEach facet group is a flat object whose **keys** carry both the bucket label and the count (`\"