{ "openapi": "3.1.0", "info": { "title": "Auto.dev Vehicle Data API", "version": "2.0.0", "description": "Automotive data for developers and AI agents: VIN decoding, specifications, listings, photos, recalls, financing, taxes, and total cost of ownership. Every endpoint takes a VIN (or a US plate) and returns JSON.\n\n## Authentication\nSend your API key as `Authorization: Bearer ` (recommended), the `?apiKey=` query parameter, or the `X-API-Key` header. Create keys in the dashboard at https://www.auto.dev/dashboard. Unauthenticated browser requests are redirected (302) to the sign-in page.\n\n## Rate limits\nThroughput is per plan. On 429, honor the `Retry-After` header.\n- **Free:** 5 requests/second — 1,000 API calls / month\n- **Growth:** 10 requests/second — Unlimited monthly volume\n- **Scale:** 50 requests/second — Unlimited monthly volume\n\n## Versioning & deprecation\nThe current major version is v2 (documented at https://docs.auto.dev). Breaking changes ship under a new major version. Endpoints scheduled for removal are announced in the docs and signaled at runtime with the `Deprecation` and `Sunset` response headers (RFC 8594) ahead of removal.\n\n## Errors\nErrors use `application/problem+json` (RFC 9457) with a machine-readable `code` and a human-readable `title`/`detail`.", "termsOfService": "https://www.auto.dev/terms", "contact": { "name": "Auto.dev Support", "url": "https://www.auto.dev", "email": "support@auto.dev" }, "license": { "name": "Auto.dev API Terms of Service", "url": "https://www.auto.dev/terms" } }, "servers": [ { "url": "https://api.auto.dev", "description": "Production API gateway" } ], "security": [ { "bearerAuth": [] }, { "apiKeyQuery": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Core", "description": "Core automotive data endpoints." }, { "name": "Marketplace", "description": "Marketplace automotive data endpoints." }, { "name": "Financial", "description": "Financial automotive data endpoints." }, { "name": "Safety", "description": "Safety automotive data endpoints." } ], "paths": { "/vin/{vin}": { "get": { "operationId": "decodeVin", "summary": "Global VIN Decode", "description": "Decode any VIN to access comprehensive vehicle data and specifications.\n\n**Plan:** Free tier and above (5 requests/second, 1,000 API calls / month).\n\n**Docs:** https://docs.auto.dev/v2/products/vin-decode", "tags": [ "Core" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VinDecodeResponse" } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/plate/{state}/{plate}": { "get": { "operationId": "plateToVin", "summary": "Plate-to-VIN", "description": "Decode US license plates to get VIN, year, make, model, and more.\n\n**Plan:** Scale tier and above (50 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/plate-to-vin", "tags": [ "Core" ], "parameters": [ { "name": "state", "in": "path", "required": true, "description": "Two-letter US state code of the plate's registration.", "schema": { "type": "string", "pattern": "[A-Za-z]{2}" }, "example": "CA" }, { "name": "plate", "in": "path", "required": true, "description": "License plate number.", "schema": { "type": "string" }, "example": "ABC123" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/plate-to-vin for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/specs/{vin}": { "get": { "operationId": "getSpecifications", "summary": "Specifications", "description": "Detailed technical specifications, features, and options for any vehicle model.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/specifications", "tags": [ "Core" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/specifications for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/build/{vin}": { "get": { "operationId": "getOemBuildData", "summary": "OEM Build Data", "description": "Original equipment manufacturer build data and production information.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/oem-build-data", "tags": [ "Core" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/oem-build-data for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/listings/{vin}": { "get": { "operationId": "getListings", "summary": "Vehicle Listings", "description": "Access millions of active vehicle listings with real-time pricing and availability.\n\n**Plan:** Free tier and above (5 requests/second, 1,000 API calls / month).\n\n**Docs:** https://docs.auto.dev/v2/products/vehicle-listings", "tags": [ "Marketplace" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/vehicle-listings for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/photos/{vin}": { "get": { "operationId": "getPhotos", "summary": "Vehicle Photos", "description": "High-quality vehicle images and photo galleries for listings and inventory.\n\n**Plan:** Free tier and above (5 requests/second, 1,000 API calls / month).\n\n**Docs:** https://docs.auto.dev/v2/products/vehicle-photos", "tags": [ "Marketplace" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/vehicle-photos for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/apr/{vin}": { "get": { "operationId": "getInterestRates", "summary": "Interest Rates", "description": "Real-time automotive financing rates and lending information.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/interest-rates", "tags": [ "Financial" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/interest-rates for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/payments/{vin}": { "get": { "operationId": "getPayments", "summary": "Vehicle Payments", "description": "Calculate monthly payments, financing options, and payment estimates.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/vehicle-payments", "tags": [ "Financial" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/vehicle-payments for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/recalls/{vin}": { "get": { "operationId": "getRecalls", "summary": "Vehicle Recalls", "description": "Safety recalls, service bulletins, and manufacturer notifications.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/vehicle-recalls", "tags": [ "Safety" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/vehicle-recalls for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/openrecalls/{vin}": { "get": { "operationId": "getOpenRecalls", "summary": "Open Recalls", "description": "Active and unresolved vehicle recall information from NHTSA.\n\n**Plan:** Scale tier and above (50 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/open-recalls", "tags": [ "Safety" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/open-recalls for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/taxes/{vin}": { "get": { "operationId": "getTaxesFees", "summary": "Taxes & Fees", "description": "Registration fees, taxes, and location-specific vehicle costs.\n\n**Plan:** Scale tier and above (50 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/taxes-fees", "tags": [ "Financial" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/taxes-fees for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/tco/{vin}": { "get": { "operationId": "getTotalCostOwnership", "summary": "Total Cost of Ownership", "description": "Comprehensive ownership costs including depreciation, maintenance, and operating expenses.\n\n**Plan:** Growth tier and above (10 requests/second, Unlimited monthly volume).\n\n**Docs:** https://docs.auto.dev/v2/products/total-cost-ownership", "tags": [ "Financial" ], "parameters": [ { "name": "vin", "in": "path", "required": true, "description": "17-character Vehicle Identification Number (letters and digits, excluding I, O, and Q).", "schema": { "type": "string", "pattern": "[A-HJ-NPR-Z0-9]{17}", "minLength": 17, "maxLength": 17 }, "example": "1FTFW3LDXRFB40317" } ], "responses": { "200": { "description": "Success. Vehicle data for the requested identifier.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "Product response object. See https://docs.auto.dev/v2/products/total-cost-ownership for the full field-level schema." } } } }, "302": { "description": "Unauthenticated browser request — redirected to the sign-in page. Send an API key (Authorization: Bearer, ?apiKey=, or X-API-Key) to receive JSON instead.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "The VIN or path parameters failed validation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "The API key is missing or invalid. Browser requests are redirected to sign in instead (302).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The authenticated plan is not entitled to this endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No data is available for the requested vehicle.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded for the current plan. Retry after the interval in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests permitted in the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key sent as `Authorization: Bearer `." }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "API key sent as the `apiKey` query parameter." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key sent as the `X-API-Key` request header." } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem detail. Returned as `application/problem+json` on any 4xx/5xx response.", "properties": { "type": { "type": "string", "format": "uri", "description": "URI identifying the problem type.", "example": "about:blank" }, "title": { "type": "string", "description": "Short, human-readable summary of the problem.", "example": "Bad Request" }, "status": { "type": "integer", "description": "HTTP status code.", "example": 400 }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "format": "uri", "description": "URI identifying this specific occurrence." }, "code": { "type": "string", "description": "Stable machine-readable error code for programmatic handling." } }, "required": [ "title", "status" ] }, "Vehicle": { "type": "object", "properties": { "vin": { "type": "string" }, "year": { "type": "integer" }, "make": { "type": "string" }, "model": { "type": "string" }, "manufacturer": { "type": "string" } } }, "VinDecodeResponse": { "type": "object", "description": "Decoded VIN with validation metadata and a normalized vehicle object.", "properties": { "vin": { "type": "string", "example": "3GCUDHEL3NG668790" }, "vinValid": { "type": "boolean" }, "wmi": { "type": "string", "description": "World Manufacturer Identifier (first 3 characters)." }, "origin": { "type": "string" }, "squishVin": { "type": "string" }, "checkDigit": { "type": "string" }, "checksum": { "type": "boolean" }, "type": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "trim": { "type": "string" }, "style": { "type": "string" }, "body": { "type": "string" }, "engine": { "type": "string" }, "drive": { "type": "string" }, "transmission": { "type": "string" }, "ambiguous": { "type": "boolean" }, "vehicle": { "$ref": "#/components/schemas/Vehicle" } } } } } }