API Documentation

Complete reference for the CarSpecsAPI. Access detailed car specifications, decode VINs, and download our full database.

Base URL: https://api.carspecsapi.com

Authentication

All API requests require an API key sent via the X-API-Key header. You can generate your API key from the Dashboard after signing up.

Keep your API key secret. Do not expose it in client-side code or public repositories. If you believe your key has been compromised, regenerate it immediately from the Dashboard.

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/makes" \
  -H "X-API-Key: YOUR_API_KEY"

Important: Requests without a valid API key will receive a 401 Unauthorized response. Requests with a key that has exceeded its plan limits will receive a 403 Forbidden response.

Base URL

All API endpoints are relative to the following base URL. All requests must be made over HTTPS. HTTP requests will be redirected.

https://api.carspecsapi.com

The current stable version is v2. All endpoints are prefixed with /v2.

Response Format

All successful responses follow a consistent envelope structure. The response body always contains a success boolean, a data field with the payload, and a meta object with request metadata.

Response Envelope

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Error responses use the same envelope, but success is set to false and data is replaced with an error object:

Error Response

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Invalid request parameter: makeId must be a positive integer."
  },
  "meta": {
    "requestId": "req_x9y8z7w6v5u4",
    "timestamp": "2026-02-16T12:00:01.000Z"
  }
}

GET

/v2/cars/makes

Find All Makes

Returns a list of all car manufacturers available in the database. Use the returned id to query models for a specific make.

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/makes" \
  -H "X-API-Key: YOUR_API_KEY"

Response — `MakeDto[]`

200 OK

{
  "success": true,
  "data": [
    { "id": 1, "name": "Acura" },
    { "id": 2, "name": "Alfa Romeo" },
    { "id": 3, "name": "Aston Martin" },
    { "id": 4, "name": "Audi" },
    { "id": 5, "name": "BMW" },
    { "id": 6, "name": "Bentley" },
    { "id": 7, "name": "Buick" },
    { "id": 8, "name": "Cadillac" },
    { "id": 9, "name": "Chevrolet" },
    { "id": 10, "name": "Chrysler" }
  ],
  "meta": {
    "requestId": "req_mk_1a2b3c4d",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Field	Type	Description
id	number	Unique identifier for the make
name	string	Display name of the manufacturer

GET

/v2/cars/makes/{makeId}/models

Find Models by Make

Returns all models for a given manufacturer. Use the makeId obtained from the Makes endpoint.

Path Parameters

Name	Type	Required	Description
makeId	number	Required	The unique ID of the make (e.g. 5 for BMW)

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/makes/5/models" \
  -H "X-API-Key: YOUR_API_KEY"

Response — `ModelDto[]`

200 OK

{
  "success": true,
  "data": [
    { "id": 101, "name": "1 Series" },
    { "id": 102, "name": "2 Series" },
    { "id": 103, "name": "3 Series" },
    { "id": 104, "name": "4 Series" },
    { "id": 105, "name": "5 Series" },
    { "id": 106, "name": "7 Series" },
    { "id": 107, "name": "X3" },
    { "id": 108, "name": "X5" },
    { "id": 109, "name": "M3" },
    { "id": 110, "name": "M5" }
  ],
  "meta": {
    "requestId": "req_md_5e6f7g8h",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Field	Type	Description
id	number	Unique identifier for the model
name	string	Display name of the model

Error Responses

Status	Description
400	Invalid makeId parameter. Must be a positive integer.
500	Internal server error. Please try again later.

GET

/v2/cars/models/{modelId}/generations

Find Generations by Model

Returns all generations (production runs) for a specific model. Each generation represents a distinct design period with year ranges.

Path Parameters

Name	Type	Required	Description
modelId	number	Required	The unique ID of the model (e.g. 103 for BMW 3 Series)

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/models/103/generations" \
  -H "X-API-Key: YOUR_API_KEY"

Response — `GenerationDto[]`

200 OK

{
  "success": true,
  "data": [
    { "id": 1001, "name": "E90", "yearFrom": 2005, "yearTo": 2011 },
    { "id": 1002, "name": "F30", "yearFrom": 2012, "yearTo": 2018 },
    { "id": 1003, "name": "G20", "yearFrom": 2019, "yearTo": 2025 }
  ],
  "meta": {
    "requestId": "req_gn_9i0j1k2l",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Field	Type	Description
id	number	Unique identifier for the generation
name	string	Generation code or name (e.g. “E90”, “F30”)
yearFrom	number	First production year for this generation
yearTo	number	Last production year for this generation

Error Responses

Status	Description
400	Invalid modelId parameter. Must be a positive integer.
500	Internal server error. Please try again later.

GET

/v2/cars/generations/{generationId}/trims

Find Trims by Generation

Returns all available trims for a specific generation. Each trim represents a unique configuration including body type, engine, and equipment level.

Path Parameters

Name	Type	Required	Description
generationId	number	Required	The unique ID of the generation (e.g. 1003 for G20)

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/generations/1003/trims" \
  -H "X-API-Key: YOUR_API_KEY"

Response — `TrimDto[]`

200 OK

{
  "success": true,
  "data": [
    {
      "id": 50001,
      "trim": "320i Sport",
      "generation": "G20",
      "bodyType": "Sedan",
      "series": "3 Series"
    },
    {
      "id": 50002,
      "trim": "330i M Sport",
      "generation": "G20",
      "bodyType": "Sedan",
      "series": "3 Series"
    },
    {
      "id": 50003,
      "trim": "M340i xDrive",
      "generation": "G20",
      "bodyType": "Sedan",
      "series": "3 Series"
    },
    {
      "id": 50004,
      "trim": "330e Plug-in Hybrid",
      "generation": "G20",
      "bodyType": "Sedan",
      "series": "3 Series"
    }
  ],
  "meta": {
    "requestId": "req_tr_3m4n5o6p",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Field	Type	Description
id	number	Unique identifier for the trim
trim	string	Full trim name including equipment level
generation	string	Generation code (e.g. “G20”)
bodyType	string	Body type (Sedan, Coupe, SUV, Hatchback, etc.)
series	string	Model series name

Error Responses

Status	Description
400	Invalid generationId parameter. Must be a positive integer.
500	Internal server error. Please try again later.

GET

/v2/cars/trims/{trimId}

Find Car Specs by ID

Returns the full specification sheet for a single trim. This endpoint delivers the most comprehensive data in the API, returning 60+ attributes covering engine, performance, dimensions, weight, fuel economy, transmission, and more.

Path Parameters

Name	Type	Required	Description
trimId	number	Required	The unique ID of the trim (e.g. 50003 for M340i xDrive)

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/trims/50003" \
  -H "X-API-Key: YOUR_API_KEY"

Response — `TrimSpecsDto`

200 OK

{
  "success": true,
  "data": {
    "id": 50003,
    "make": "BMW",
    "model": "3 Series",
    "generation": "G20",
    "trim": "M340i xDrive",
    "year": 2023,
    "bodyType": "Sedan",
    "series": "3 Series",

    "engineType": "Gasoline",
    "engineCylinders": "6",
    "engineDisplacementCc": 2998,
    "engineDisplacementLiters": "3.0",
    "engineHorsepowerHp": 382,
    "engineHorsepowerRpm": "5800",
    "engineTorqueNm": 500,
    "engineTorqueLbFt": 369,
    "engineTorqueRpm": "1800-5000",
    "engineConfiguration": "Inline",
    "engineValvesPerCylinder": 4,
    "engineValveTrain": "DOHC",
    "engineAspiration": "Twin-turbocharged",
    "engineCompression": "10.2:1",
    "engineBoreMm": 82.0,
    "engineStrokeMm": 94.6,

    "fuelType": "Gasoline",
    "fuelSystem": "Direct injection",
    "fuelTankCapacityLiters": 59,
    "fuelTankCapacityGallons": 15.6,
    "fuelEconomyCityMpg": 23,
    "fuelEconomyHighwayMpg": 32,
    "fuelEconomyCombinedMpg": 26,
    "fuelEconomyCityLper100km": 10.2,
    "fuelEconomyHighwayLper100km": 7.4,
    "fuelEconomyCombinedLper100km": 9.0,
    "co2EmissionsGPerKm": 206,

    "transmissionType": "Automatic",
    "transmissionGears": 8,
    "transmissionName": "8-speed Steptronic Sport",
    "driveType": "All-wheel drive",

    "acceleration0To100KmhS": 4.4,
    "acceleration0To60MphS": 4.1,
    "topSpeedKmh": 250,
    "topSpeedMph": 155,

    "lengthMm": 4709,
    "widthMm": 1827,
    "heightMm": 1435,
    "wheelbaseMm": 2851,
    "frontTrackMm": 1584,
    "rearTrackMm": 1589,
    "groundClearanceMm": 136,
    "curbWeightKg": 1730,
    "curbWeightLbs": 3814,
    "grossWeightKg": 2210,

    "cargoVolumeLiters": 480,
    "cargoVolumeCuFt": 17.0,

    "seatingCapacity": 5,
    "doors": 4,

    "frontSuspension": "Double-joint spring strut",
    "rearSuspension": "Five-link",
    "frontBrakes": "Ventilated disc",
    "rearBrakes": "Ventilated disc",
    "steeringType": "Rack and pinion, electric",
    "turningCircleM": 11.4,

    "tireSizeFront": "225/45 R18",
    "tireSizeRear": "255/40 R18",
    "wheelSizeFront": "18 x 8.0",
    "wheelSizeRear": "18 x 8.5"
  },
  "meta": {
    "requestId": "req_ts_7q8r9s0t",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Note: The TrimSpecsDto contains 60+ attributes. Some fields may be null if the data is not available for a specific trim. All numeric values use their standard units as indicated by the field name suffix.

Error Responses

Status	Description
400	Invalid trimId parameter. Must be a positive integer.
500	Internal server error. Please try again later.

POST

/v2/vin-decoder/decode

VIN Decoder

Decodes a 17-character Vehicle Identification Number (VIN) and returns comprehensive vehicle information. The decoder returns up to 145 decoded attributes including make, model, year, engine specifications, safety features, and equipment details.

Note: The VIN decoder works best for US-market vehicles. Results for vehicles sold outside the United States may have limited data or reduced accuracy.

Request Body (JSON)

Name	Type	Required	Description
vin	string	Required	The 17-character Vehicle Identification Number
year	number	Optional	Model year override. Helps improve accuracy for VINs where the year digit is ambiguous (e.g. 2000 vs 2030).

cURL

curl -X POST "https://api.carspecsapi.com/v2/vin-decoder/decode" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vin": "WBA5R1C50KAK09087",
    "year": 2019
  }'

Response — `VinDecodeResponseDto`

200 OK

{
  "success": true,
  "data": {
    "vin": "WBA5R1C50KAK09087",
    "year": 2019,
    "make": "BMW",
    "model": "3 Series",
    "trim": "330i",
    "bodyClass": "Sedan/Saloon",
    "doors": 4,
    "driveType": "Rear-Wheel Drive",

    "engineCylinders": 4,
    "engineDisplacementL": 2.0,
    "engineHP": 255,
    "engineKW": 190,
    "engineManufacturer": "BMW",
    "engineModel": "B48B20",
    "fuelTypePrimary": "Gasoline",
    "engineConfiguration": "Inline",
    "engineTurbo": "Twin-scroll turbocharged",
    "valveTrain": "DOHC",
    "transmissionStyle": "Automatic",
    "transmissionSpeeds": 8,

    "abs": "Standard",
    "activeSafety": "Standard",
    "adaptiveCruiseControl": "Optional",
    "adaptiveDrivingBeam": "Optional",
    "adaptiveHeadlights": "Standard",
    "airBagFrontSide": "Standard",
    "airBagKnee": "Standard",
    "airBagCurtain": "Standard",
    "automaticEmergencyBraking": "Standard",
    "blindSpotWarning": "Optional",
    "daytimeRunningLight": "Standard",
    "electronicStabilityControl": "Standard",
    "forwardCollisionWarning": "Standard",
    "laneDepartureWarning": "Standard",
    "laneKeepAssist": "Optional",
    "parkingAssist": "Optional",
    "rearCrossTrafficAlert": "Optional",
    "rearVisibilitySystem": "Standard",
    "tirePressureMonitoring": "Standard",
    "tractionControl": "Standard",

    "plantCity": "Munich",
    "plantCountry": "Germany",
    "plantCompanyName": "BMW AG",
    "manufacturer": "BMW",
    "manufacturerId": 968,

    "gvwr": "Class 1C: 4,001 - 5,000 lb",
    "curbWeightLb": 3582,
    "wheelBaseLong": "112.2",
    "overallLength": "185.7",
    "overallWidth": "71.9",
    "overallHeight": "56.8",

    "steeringLocation": "Left",
    "entertainmentSystem": "Standard",
    "windows": "Power",
    "seatBeltsType": "3-point",
    "seatRows": 2,
    "seats": 5,

    "...": "(145 total attributes)"
  },
  "meta": {
    "requestId": "req_vn_1u2v3w4x",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

Note: The response includes up to 145 attributes. The example above is truncated. Attributes may be null or absent when data is not available for a specific VIN.

Error Responses

Status	Description
400	Invalid VIN format. Must be exactly 17 alphanumeric characters (excluding I, O, Q).
500	Internal server error or upstream decoder failure. Please try again later.

GET

/v2/cars/download-database

Database Download

Database Plan Only — This feature requires the Database plan ($799/year). Calls from other plans will receive a 403 Forbidden response.

Download the complete CarSpecs database as a structured file. Two endpoints are available:

GET

/v2/cars/download-database

Downloads the raw database containing all car specifications. Returns a JSON file with the full dataset.

GET

/v2/cars/download-database-generated

Downloads a generated, enriched version of the database with additional computed fields and normalized data structures.

cURL

curl -X GET "https://api.carspecsapi.com/v2/cars/download-database" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o carspecs-database.json

Limit	Value
Downloads per year	100
Required plan	Database ($799/yr)
Format	JSON

Error Responses

Status	Description
403	Forbidden. Your plan does not include database download access, or you have exceeded the 100 downloads/year limit.
500	Internal server error. Please try again later.

Rate Limiting

API requests are rate-limited based on your subscription plan. Rate limits are enforced on a per-day basis and reset at midnight UTC. When you exceed your limit, requests will return a 429 Too Many Requests response.

Plan	Daily Limit	Price
Free	100 requests/day	$0
Starter	1,500 requests/day	Paid
Pro	6,000 requests/day	Paid
Database	6,000 requests/day	$799/yr

Rate Limit Headers

Every API response includes rate-limit headers so you can track your usage programmatically:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed per day for your plan
X-RateLimit-Remaining	Number of requests remaining in the current period
X-RateLimit-Reset	Unix timestamp (seconds) when the rate limit resets

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 5847
X-RateLimit-Reset: 1739836800

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Daily limit of 6000 requests reached. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "req_rl_5y6z7a8b",
    "timestamp": "2026-02-16T23:59:59.000Z"
  }
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error, and codes in the 5xx range indicate a server error.

Code	Status	Description
200	OK	The request was successful and the response contains the requested data.
400	Bad Request	The request was malformed or contained invalid parameters. Check the error message for details on which parameter is invalid.
401	Unauthorized	No API key was provided, or the provided key is invalid. Include a valid `X-API-Key` header.
403	Forbidden	Your API key is valid but does not have permission to access the requested resource. This typically occurs when accessing Database-plan-only endpoints on a lower plan.
404	Not Found	The requested resource does not exist. Verify the ID in your request path is correct.
429	Too Many Requests	You have exceeded the rate limit for your plan. Wait until the limit resets at midnight UTC or upgrade your plan for higher limits.
500	Internal Server Error	An unexpected error occurred on the server. If this persists, please contact support.
502	Bad Gateway	The API server received an invalid response from an upstream service. This is usually temporary — retry after a brief delay.

Error Response Example

401 Unauthorized

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid or missing API key. Provide a valid X-API-Key header."
  },
  "meta": {
    "requestId": "req_er_9c0d1e2f",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Resource not found. No trim exists with id 999999."
  },
  "meta": {
    "requestId": "req_er_3g4h5i6j",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

502 Bad Gateway

{
  "success": false,
  "error": {
    "code": 502,
    "message": "Bad gateway. The upstream service returned an invalid response. Please retry."
  },
  "meta": {
    "requestId": "req_er_7k8l9m0n",
    "timestamp": "2026-02-16T12:00:00.000Z"
  }
}

API Documentation

Authentication

Base URL

Response Format

Find All Makes

Response — MakeDto[]

Find Models by Make

Path Parameters

Response — ModelDto[]

Error Responses

Find Generations by Model

Path Parameters

Response — GenerationDto[]

Error Responses

Find Trims by Generation

Path Parameters

Response — TrimDto[]

Error Responses

Find Car Specs by ID

Path Parameters

Response — TrimSpecsDto

Error Responses

VIN Decoder

Request Body (JSON)

Response — VinDecodeResponseDto

Error Responses

Database Download

Error Responses

Rate Limiting

Rate Limit Headers

Error Codes

Error Response Example

Response — `MakeDto[]`

Response — `ModelDto[]`

Response — `GenerationDto[]`

Response — `TrimDto[]`

Response — `TrimSpecsDto`

Response — `VinDecodeResponseDto`