Documentation
Overview Quick Start Authentication API Endpoints Code Examples Error Codes Rate Limits Changelog
Swagger UI ReDoc

API Endpoints

Complete reference for all VIN Decoder API endpoints.

POST /api/v1/decode

Decode a Vehicle Identification Number (VIN) and retrieve comprehensive vehicle information.

Request Body
Parameter Type Required Description
vin string Required 17-character Vehicle Identification Number
Example Request
curl -X POST https://api.vinreveal.com/api/v1/decode \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"vin": "WAUAFAFL1DN015882"}'
Response
{
  "vin": "WAUAFAFL1DN015882",
  "valid": true,
  "year": 2013,
  "make": "Audi",
  "model": "A4",
  "manufacturer": "Audi AG",
  "engine": "2.0L Turbo",
  "country": "Germany",
  "assembly_plant": "Ingolstadt",
  "body_type": "Sedan",
  "drive_type": "AWD",
  "vehicle_type": "Passenger Car",
  "wmi": "WAU",
  "vds": "AFAFL1",
  "vis": "DN015882",
  "sequential_number": "015882",
  "check_digit": "1",
  "model_year_code": "D",
  "plant_code": "N",
  "decoded_at": "2024-01-20T15:30:45Z"
}
{
  "error": "Invalid VIN format",
  "detail": "VIN must be exactly 17 characters"
}
{
  "detail": "Authentication credentials were not provided."
}
{
  "error": "Subscription limit exceeded",
  "detail": "You have exceeded your monthly decode limit of 1000",
  "usage": {
    "used": 1000,
    "limit": 1000,
    "resets_at": "2024-02-01T00:00:00Z"
  }
}
GET /api/v1/decode/{vin}

Retrieve previously decoded VIN information from cache. This endpoint doesn't count against your usage quota.

Path Parameters
Parameter Type Required Description
vin string Required 17-character Vehicle Identification Number
Example Request
curl -X GET https://api.vinreveal.com/api/v1/decode/WAUAFAFL1DN015882 \
  -H "X-API-Key: your-api-key-here"
Response

Returns the same response format as the POST /decode endpoint if the VIN is found in cache. Returns 404 if not found.

GET /api/v1/user/usage

Get your current API usage statistics including monthly limits and remaining quota.

Example Request
curl -X GET https://api.vinreveal.com/api/v1/user/usage \
  -H "X-API-Key: your-api-key-here"
Response
{
  "subscription_tier": "professional",
  "monthly_limit": 5000,
  "used_this_month": 1523,
  "remaining": 3477,
  "percentage_used": 30.46,
  "reset_date": "2024-02-01T00:00:00Z",
  "daily_usage": {
    "today": 45,
    "yesterday": 62,
    "last_7_days": 312,
    "last_30_days": 1523
  },
  "rate_limits": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  }
}
GET /api/v1/user/history

Retrieve your VIN decode history with filtering and pagination options.

Query Parameters
Parameter Type Required Description
page integer Optional Page number (default: 1)
page_size integer Optional Results per page (default: 20, max: 100)
start_date string Optional Filter by start date (YYYY-MM-DD)
end_date string Optional Filter by end date (YYYY-MM-DD)
make string Optional Filter by vehicle make
Example Request
curl -X GET "https://api.vinreveal.com/api/v1/user/history?page=1&page_size=10&make=Audi" \
  -H "X-API-Key: your-api-key-here"
Response
{
  "count": 156,
  "next": "https://api.vinreveal.com/api/v1/user/history?page=2&page_size=10",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "vin": "WAUAFAFL1DN015882",
      "make": "Audi",
      "model": "A4",
      "year": 2013,
      "decoded_at": "2024-01-20T15:30:45Z",
      "valid": true
    },
    // ... more results
  ]
}
GET /api/v1/keys

List all your API keys and their status.

Example Request
curl -X GET https://api.vinreveal.com/api/v1/keys \
  -H "Authorization: Token your-token-here"
Response
{
  "keys": [
    {
      "id": "key_123456",
      "name": "Production API Key",
      "key": "vr_live_abcd1234...",
      "created_at": "2024-01-15T10:00:00Z",
      "last_used": "2024-01-20T15:30:45Z",
      "is_active": true,
      "permissions": ["decode", "history", "usage"]
    }
  ]
}
POST /api/v1/keys

Create a new API key for your account.

Request Body
Parameter Type Required Description
name string Required Descriptive name for the API key
permissions array Optional List of permissions (default: all)
Example Request
curl -X POST https://api.vinreveal.com/api/v1/keys \
  -H "Authorization: Token your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production API Key"}'
DELETE /api/v1/keys/{key_id}

Delete (revoke) an API key.

Path Parameters
Parameter Type Required Description
key_id string Required The ID of the API key to delete
Example Request
curl -X DELETE https://api.vinreveal.com/api/v1/keys/key_123456 \
  -H "Authorization: Token your-token-here"
Response
{
  "message": "API key successfully deleted"
}

Additional Resources