openapi: 3.0.0
info:
version: 1.10.20
title: Car API
description: |
Welcome to [CarAPIs vehicle API](https://carapi.app) documentation. The developer friendly Car API.
Start developing with your vehicle API today — no fees, no signup. CarAPIs free vehicle data-set
requires no account. Only pay when you're ready to go live. The free data-set is limited to 2015-2020 vehicles.
To access the full data-set you may [signup here](https://carapi.app/register) and then select a subscription plan.
**Additional Documentation**
For additional documentation please review [https://carapi.app/docs](https://carapi.app/docs).
**SDKs**
PHP SDK: [https://github.com/car-api-team/carapi-php-sdk](https://github.com/car-api-team/carapi-php-sdk)
**Release Updates**
Check release history here: [https://github.com/car-api-team/docs/releases](https://github.com/car-api-team/docs/releases)
servers:
- url: https://carapi.app
tags:
- name: Account
- name: Auth
- name: Bodies
- name: Colors (Exterior)
- name: Colors (Interior)
- name: Data Feeds
- name: Engines
- name: Makes
- name: Mileages
- name: Models
- name: Trims
- name: Vehicle Attributes
- name: Vin Decoder
- name: Years
paths:
"/api/account/requests":
get:
operationId: account:requests:get
summary: Car API Get API Usage
description: |-
Returns the total requests made by your account since last month to rate-limited endpoints. All dates are
reported using UTC/GMT -5 (US Eastern Standard Time).
tags:
- Account
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
items:
properties:
date:
example: '2023-01-01'
type: string
format: date
count:
example: 203
type: integer
type: array
application/ld+json:
schema:
items:
properties:
date:
example: '2023-01-01'
type: string
format: date
count:
example: 203
type: integer
type: array
application/hal+json:
schema:
items:
properties:
date:
example: '2023-01-01'
type: string
format: date
count:
example: 203
type: integer
type: array
'400':
description: BadRequestException
content:
application/json:
schema:
title: BadRequestException
properties:
exception:
example: BadRequestException
type: string
code:
example: 400
type: string
url:
example: "/url/path"
type: string
message:
example: The request contains invalid data. The returned error message should indicate the issue.
type: string
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
title: MethodNotAllowedException
properties:
exception:
example: MethodNotAllowedException
type: string
code:
example: 405
type: string
url:
example: "/url/path"
type: string
message:
example: The HTTP method used to request this resource is not valid. For example, using an HTTP POST when the endpoint only accepts HTTP GET.
type: string
'429':
description: 'TooManyRequestsException - Max Per Minute: 600'
content:
application/json:
schema:
title: TooManyRequestsException
properties:
exception:
example: TooManyRequestsException
type: string
code:
example: 429
type: string
url:
example: "/url/path"
type: string
message:
example: 'TooManyRequestsException - Max Per Minute: 600 (note: daily rate limits may apply, see your subscription plans details)'
type: string
'500':
description: UnauthenticatedException
content:
application/json:
schema:
"$ref": "#/components/schemas/Exception"
application/ld+json:
schema:
"$ref": "#/components/schemas/Exception"
application/hal+json:
schema:
"$ref": "#/components/schemas/Exception"
'503':
description: ServiceUnavailableException
content:
application/json:
schema:
title: ServiceUnavailableException
properties:
exception:
example: ServiceUnavailableException
type: string
code:
example: 503
type: string
url:
example: "/url/path"
type: string
message:
example: The server is unavailable, typically only encountered during scheduled maintenance.
type: string
security:
- bearerAuth: []
"/api/account/requests-today":
get:
operationId: account:requeststoday:get
summary: Car API Get Today's API Usage
description: |-
Returns the total requests made by your account today to rate-limited endpoints. All dates are
reported using UTC/GMT -5 (US Eastern Standard Time).
tags:
- Account
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
count:
example: 42
type: integer
type: object
application/ld+json:
schema:
properties:
count:
example: 42
type: integer
type: object
application/hal+json:
schema:
properties:
count:
example: 42
type: integer
type: object
'400':
description: BadRequestException
content:
application/json:
schema:
title: BadRequestException
properties:
exception:
example: BadRequestException
type: string
code:
example: 400
type: string
url:
example: "/url/path"
type: string
message:
example: The request contains invalid data. The returned error message should indicate the issue.
type: string
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
title: MethodNotAllowedException
properties:
exception:
example: MethodNotAllowedException
type: string
code:
example: 405
type: string
url:
example: "/url/path"
type: string
message:
example: The HTTP method used to request this resource is not valid. For example, using an HTTP POST when the endpoint only accepts HTTP GET.
type: string
'500':
description: UnauthenticatedException
content:
application/json:
schema:
"$ref": "#/components/schemas/Exception"
application/ld+json:
schema:
"$ref": "#/components/schemas/Exception"
application/hal+json:
schema:
"$ref": "#/components/schemas/Exception"
'503':
description: ServiceUnavailableException
content:
application/json:
schema:
title: ServiceUnavailableException
properties:
exception:
example: ServiceUnavailableException
type: string
code:
example: 503
type: string
url:
example: "/url/path"
type: string
message:
example: The server is unavailable, typically only encountered during scheduled maintenance.
type: string
security:
- bearerAuth: []
"/api/auth/login":
post:
operationId: auth:api:post
summary: Car API JWT Login
description: |-
CarAPI uses JSON Web Tokens (JWT) to authenticate requests. You can generate a JWT using your API Token and
API Secret in SwaggerUI (this page) with the following steps:
- Click the "Try Out" button
- Enter API Token and API Secret in the JSON payload.
- Click Execute
- A JWT will be returned if the credentials are correct
- Next click the "Authorize" button at the top-right of Swagger UI (this page) and paste in the JWT.
Your JWT will now be sent with any request you make in Swagger until you refresh the page.
In your application code, Postman or cURL, you will need to pass the token in the HTTP Header as:
```
Authorization: Bearer {TOKEN_VALUE_HERE}
```
You should cache your JWT to avoid having to authenticate on each request. You must check the token's
expiration value to determine when you need to generate a new token. Please refer to
[https://jwt.io/](https://jwt.io/) to learn more about JSON Web Tokens.
Your email address and password cannot be used to generate a JWT. You must use your API token and secret.
If you don't yet have API credentials you must first [register](/register) and then generate a secret.
Users without a subscription will have limited data access.
For additional documentation please review [https://carapi.app/docs](https://carapi.app/docs).
tags:
- Auth
requestBody:
content:
application/json:
schema:
required:
- api_token
- api_secret
properties:
api_token:
example: ''
type: string
api_secret:
example: ''
type: string
type: object
parameters: []
responses:
'200':
description: ''
content:
text/plain:
schema:
type: string
'400':
description: BadRequestException
content:
text/plain:
schema:
type: string
'401':
description: Authentication Failed
content:
text/plain:
schema:
type: string
'405':
description: MethodNotAllowedException
content:
text/plain:
schema:
type: string
'429':
description: 'TooManyRequestsException - Max Per Minute: 20'
content:
text/plain:
schema:
type: string
'500':
description: ServiceUnavailableException
content:
text/plain:
schema:
type: string
'503':
description: ServiceUnavailableException
content:
text/plain:
schema:
type: string
"/api/bodies":
get:
operationId: makemodeltrimbodies:index:get
summary: Car API Search vehicle bodies
description: |-
To include additional information about the returned body (such as year, make, model and trim) request with the
query parameter as `verbose=yes`.
For complex queries you may use the json field to send an array of URL encoded JSON conditions, example:
`[{"field": "doors", "op": ">=", "val": 4}, {"field": "type", "op": "in", "val": ["SUV","Van"]}]`
See `/api/vehicle-attributes` for a complete list of vehicle attributes.
JSON operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not in`, `like`, `not like`, `not null`, and `is null`.
JSON search fields:
`year`, `make`, `model`, `trim`, `type`, `doors`, `seats`, `length`, `width`, `height`, `wheel_base`, `front_track`, `rear_track`, `ground_clearance`, `cargo_capacity`, `max_cargo_capacity`, `curb_weight`, `gross_weight`, `max_payload`, `max_towing_capacity`, `make_model_trim_id`, `created`, `modified`, `make_id`, and `make_model_id`.
tags:
- Bodies
externalDocs:
url: https://carapi.app/features/json-api-specs#bodies
description: Documentation
parameters:
- "$ref": "#/x-swagger-bake/components/parameters/paginatorPage"
- "$ref": "#/x-swagger-bake/components/parameters/paginatorLimit"
- in: query
name: sort
required: false
schema:
type: string
enum:
- id
- make_model_trim_id
- type
- doors
- length
- width
- seats
- height
- wheel_base
- front_track
- rear_track
- ground_clearance
- cargo_capacity
- max_cargo_capacity
- curb_weight
- gross_weight
- max_payload
- max_towing_capacity
- "$ref": "#/x-swagger-bake/components/parameters/paginatorDirection"
- in: query
name: verbose
description: Includes make, model and trim
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- in: query
name: make_model_id
required: false
schema:
type: string
description: Value
- in: query
name: make_id
required: false
schema:
type: string
description: Value
- in: query
name: year
required: false
schema:
type: string
description: Value
- in: query
name: make
required: false
schema:
type: string
description: Like
- in: query
name: model
required: false
schema:
type: string
description: Like
- in: query
name: trim
required: false
schema:
type: string
description: Like
- in: query
name: make_model_trim_id
required: false
schema:
type: string
description: Value
- in: query
name: type
required: false
schema:
type: string
description: Like
- in: query
name: doors
required: false
schema:
type: string
description: Value
- in: query
name: json
required: false
schema:
type: string
description: JsonSearchFilter
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
items:
type: object
allOf:
- "$ref": "#/components/schemas/MakeModelTrimBody"
type: array
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/Generic-Collection"
application/ld+json:
schema:
properties:
member:
items:
type: object
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/JsonLd-Item"
- "$ref": "#/components/schemas/MakeModelTrimBody"
type: array
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/JsonLd-Collection"
application/hal+json:
schema:
properties:
_embedded:
items:
type: object
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/HalJson-Item"
- "$ref": "#/components/schemas/MakeModelTrimBody"
type: array
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/HalJson-Collection"
'400':
description: BadRequestException
content:
application/json:
schema:
title: BadRequestException
properties:
exception:
example: BadRequestException
type: string
code:
example: 400
type: string
url:
example: "/url/path"
type: string
message:
example: The request contains invalid data. The returned error message should indicate the issue.
type: string
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
title: MethodNotAllowedException
properties:
exception:
example: MethodNotAllowedException
type: string
code:
example: 405
type: string
url:
example: "/url/path"
type: string
message:
example: The HTTP method used to request this resource is not valid. For example, using an HTTP POST when the endpoint only accepts HTTP GET.
type: string
'429':
description: 'TooManyRequestsException - Max Per Minute: 600'
content:
application/json:
schema:
title: TooManyRequestsException
properties:
exception:
example: TooManyRequestsException
type: string
code:
example: 429
type: string
url:
example: "/url/path"
type: string
message:
example: 'TooManyRequestsException - Max Per Minute: 600 (note: daily rate limits may apply, see your subscription plans details)'
type: string
'503':
description: ServiceUnavailableException
content:
application/json:
schema:
title: ServiceUnavailableException
properties:
exception:
example: ServiceUnavailableException
type: string
code:
example: 503
type: string
url:
example: "/url/path"
type: string
message:
example: The server is unavailable, typically only encountered during scheduled maintenance.
type: string
security:
- bearerAuth: []
"/api/data-feeds/download":
get:
operationId: datafeeds:download:get
summary: Car API Get Data Feed
description: |-
Returns a datafeed as a CSV compressed in a ZIP for download, you must subscribe to this product through your
dashboard.
tags:
- Data Feeds
externalDocs:
url: https://carapi.app/sample-opendatafeed
description: ''
parameters: []
responses:
'200':
description: ''
content:
text/plain:
schema:
type: string
format: file
'400':
description: BadRequestException
content:
text/plain:
schema:
type: string
'401':
description: Authentication Failed
content:
text/plain:
schema:
type: string
'403':
description: ForbiddenException
content:
text/plain:
schema:
type: string
'405':
description: MethodNotAllowedException
content:
text/plain:
schema:
type: string
'429':
description: 'TooManyRequestsException - Max Per Minute: 600'
content:
text/plain:
schema:
type: string
'500':
description: ServiceUnavailableException
content:
text/plain:
schema:
type: string
application/json:
schema:
"$ref": "#/components/schemas/Exception"
application/ld+json:
schema:
"$ref": "#/components/schemas/Exception"
application/hal+json:
schema:
"$ref": "#/components/schemas/Exception"
'503':
description: ServiceUnavailableException
content:
text/plain:
schema:
type: string
security:
- bearerAuth: []
"/api/data-feeds/last-updated":
get:
operationId: datafeeds:lastupdated:get
summary: Car API Data Feed Last Updated
description: Returns last modified timestamp of the data feed. All times are United States Eastern Standard Time (EST).
tags:
- Data Feeds
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
last_updated:
example: '2023-01-01 12:00:00'
type: string
format: date-time
type: object
application/ld+json:
schema:
properties:
last_updated:
example: '2023-01-01 12:00:00'
type: string
format: date-time
type: object
application/hal+json:
schema:
properties:
last_updated:
example: '2023-01-01 12:00:00'
type: string
format: date-time
type: object
'400':
description: BadRequestException
content:
application/json:
schema:
title: BadRequestException
properties:
exception:
example: BadRequestException
type: string
code:
example: 400
type: string
url:
example: "/url/path"
type: string
message:
example: The request contains invalid data. The returned error message should indicate the issue.
type: string
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
title: MethodNotAllowedException
properties:
exception:
example: MethodNotAllowedException
type: string
code:
example: 405
type: string
url:
example: "/url/path"
type: string
message:
example: The HTTP method used to request this resource is not valid. For example, using an HTTP POST when the endpoint only accepts HTTP GET.
type: string
'429':
description: 'TooManyRequestsException - Max Per Minute: 600'
content:
application/json:
schema:
title: TooManyRequestsException
properties:
exception:
example: TooManyRequestsException
type: string
code:
example: 429
type: string
url:
example: "/url/path"
type: string
message:
example: 'TooManyRequestsException - Max Per Minute: 600 (note: daily rate limits may apply, see your subscription plans details)'
type: string
'503':
description: ServiceUnavailableException
content:
application/json:
schema:
title: ServiceUnavailableException
properties:
exception:
example: ServiceUnavailableException
type: string
code:
example: 503
type: string
url:
example: "/url/path"
type: string
message:
example: The server is unavailable, typically only encountered during scheduled maintenance.
type: string
security:
- bearerAuth: []
"/api/engines":
get:
operationId: makemodeltrimengines:index:get
summary: Car API Search vehicle engines
description: |-
To include additional information about the returned body (such as year, make, model and trim) request with the
query parameter as `verbose=yes`.
For complex queries you may use the json field to send an array of URL encoded JSON conditions, example:
`[{"field": "horsepower_hp", "op": ">=", "val": 100}, {"field": "horsepower_hp", "op": "<=", "val": 300}]`
See `/api/vehicle-attributes` for a complete list of vehicle attributes.
JSON operators: `=`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not in`, `like`, `not like`, `not null`, and `is null`.
JSON search fields:
`year`, `make`, `model`, `trim`, `fuel_type`, `engine_type`, `transmission`, `drive_type`, `cam_type`, `valve_timing`, `valves`, `horsepower_hp`, `size`, `cylinders`, `created`, `modified`, `make_id`, `make_model_id`, and `make_model_trim_id`.
tags:
- Engines
externalDocs:
url: https://carapi.app/features/json-api-specs#engines
description: Documentation
parameters:
- "$ref": "#/x-swagger-bake/components/parameters/paginatorPage"
- "$ref": "#/x-swagger-bake/components/parameters/paginatorLimit"
- in: query
name: sort
required: false
schema:
type: string
enum:
- id
- make_model_trim_id
- engine_type
- fuel_type
- cylinders
- size
- horsepower_hp
- horsepower_rpm
- torque_ft_lbs
- torque_rpm
- valves
- valve_timing
- cam_type
- drive_type
- transmission
- "$ref": "#/x-swagger-bake/components/parameters/paginatorDirection"
- in: query
name: verbose
description: Includes make, model and trim
required: false
schema:
type: string
enum:
- 'yes'
- 'no'
- in: query
name: make_model_trim_id
required: false
schema:
type: string
description: Value
- in: query
name: cylinders
required: false
schema:
type: string
description: Like
- in: query
name: size
required: false
schema:
type: string
description: Value
- in: query
name: horsepower_hp
required: false
schema:
type: string
description: Value
- in: query
name: valves
required: false
schema:
type: string
description: Value
- in: query
name: valve_timing
required: false
schema:
type: string
description: Like
- in: query
name: cam_type
required: false
schema:
type: string
description: Like
- in: query
name: drive_type
required: false
schema:
type: string
description: Like
- in: query
name: transmission
required: false
schema:
type: string
description: Like
- in: query
name: engine_type
required: false
schema:
type: string
description: Like
- in: query
name: fuel_type
required: false
schema:
type: string
description: Like
- in: query
name: make_model_id
required: false
schema:
type: string
description: Value
- in: query
name: make_id
required: false
schema:
type: string
description: Value
- in: query
name: year
required: false
schema:
type: string
description: Value
- in: query
name: make
required: false
schema:
type: string
description: Like
- in: query
name: model
required: false
schema:
type: string
description: Like
- in: query
name: trim
required: false
schema:
type: string
description: Like
- in: query
name: json
required: false
schema:
type: string
description: JsonSearchFilter
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
items:
type: object
allOf:
- "$ref": "#/components/schemas/MakeModelTrimEngine"
type: array
allOf:
- "$ref": "#/x-swagger-bake/components/schemas/Generic-Collection"
application/ld+json:
schema:
properties:
member:
items:
type: object
allOf:
- "$ref": "#/x-swagger-bak
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/car-api/refs/heads/main/openapi/car-api-openapi-original.yml