Body
Description
email
string (required)
password
string (required)
API Documentation
Overview
This page documents the API routes defined in backend API modules:/api/v1/users,/api/v1/decode, and/api/v1/vag-map.
Guest decode endpoints are intentionally omitted here.
Authentication
Protected routes require a bearer token, not a raw API key in headers.
There are two alternative ways to get the same auth token: either call /api/v1/users/signin with email/password, or call /api/v1/users/token with an API key created in the dashboard.
Each endpoint already returns the bearer token in its response; do not call both unless you intentionally want to re-authenticate.
POST /api/v1/users/signin
Content-Type: application/json
{
"email": "dev@company.com",
"password": "your-password"
}
POST /api/v1/users/token
Content-Type: application/json
{
"api_key": "key_xxx"
}
{
"user_id": "usr_xxx",
"token": "ipHash.uaHash.jwtPart1.jwtPart2.jwtPart3",
"expires_in": 3600
}
Use the returned token for protected endpoints:
Authorization: Bearer <token>
Get Auth Token
Get auth token in one request: use /api/v1/users/signin with email/password or /api/v1/users/token with API key. Both returntoken in the response.
Create/Get API Key
Create API key in client dashboard on Dashboard API page, then exchange it via POST /api/v1/users/token. You can also create additional keys via /api/v1/users/{user_id}/api_key after authentication.
Find User ID
The user_id is returned by both/api/v1/users/signin and/api/v1/users/token responses.
Users API
Base path: /api/v1/users
POST/api/v1/users/signin
Authentication: Not required
Request schema
Response schema
Field
Description
user_id
string
token
string, bearer token
expires_in
number, seconds
Notes: Exchanges email/password directly into auth token (single request).
Request example
POST /api/v1/users/signin
Content-Type: application/json
{
"email": "dev@company.com",
"password": "your-password"
}Response example
{
"user_id": "usr_xxx",
"token": "ipHash.uaHash.jwtPart1.jwtPart2.jwtPart3",
"expires_in": 3600
}POST/api/v1/users/token
Authentication: Not required
Request schema
Body
Description
api_key
string (required)
Response schema
Field
Description
user_id
string
token
string, bearer token
expires_in
number, seconds
Notes: Exchanges existing API key (from dashboard) into auth token (single request).
Request example
POST /api/v1/users/token
Content-Type: application/json
{
"api_key": "key_xxx"
}Response example
{
"user_id": "usr_xxx",
"token": "ipHash.uaHash.jwtPart1.jwtPart2.jwtPart3",
"expires_in": 3600
}GET/api/v1/users/{user_id}
Authentication: Bearer token (How to get a token)
Path parameters
user_id - string (required) (Get user_id)
Request schema
Headers
Description
Authorization
Bearer <token>
Response schema
Field
Description
user_id
string
name
string
email
string
role
string
Request example
GET /api/v1/users/usr_xxx
Authorization: Bearer <token>Response example
{
"user_id": "usr_xxx",
"name": "Jane Doe",
"email": "dev@company.com",
"role": "client"
}POST/api/v1/users/{user_id}/api_key
Authentication: Bearer token (How to get a token)
Path parameters
user_id - string (required) (Get user_id)
Request schema
Body
Description
name
string (required, min 1, max 255)
Response schema
Field
Description
api_key
string
Request example
POST /api/v1/users/usr_xxx/api_key
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "My Integration Key"
}Response example
{
"api_key": "key_live_xxx"
}Decode API (Authenticated Endpoints)
Base path: /api/v1/decode
GET/api/v1/decode/{user_id}
Authentication: Bearer token (How to get a token)
Path parameters
user_id - string (required) (Get user_id)
Request schema
Query
Description
vin
string (required, length 17)
force
boolean (optional, default false)
Response schema
Field
Description
task_state
string
task_id
string | null
task_result (object | null
make, model, body_type, year, tab_names, tabs)
success
boolean
message
string | null
Request example
GET /api/v1/decode/usr_xxx?vin=WBAJA7105LB123456&force=false
Authorization: Bearer <token>Response example
{
"task_state": "completed",
"task_id": null,
"task_result": {
"make": "BMW",
"model": "3 Series",
"body_type": "Sedan",
"year": "2020",
"tab_names": ["Identification"],
"tabs": {}
},
"success": true,
"message": "Vin decoded"
}POST/api/v1/decode/{user_id}
Authentication: Bearer token (How to get a token)
Path parameters
user_id - string (required) (Get user_id)
Request schema
Body
Description
vins
string[] (required, VIN length 17 each)
file_name
string | null (optional)
bulk_id
number | null (optional)
Response schema
Field
Description
task_state
string
task_ids
string[]
success
boolean
message
string | null
Notes: Used for bulk decode (multiple VINs in one request).
Request example
POST /api/v1/decode/usr_xxx
Authorization: Bearer <token>
Content-Type: application/json
{
"vins": ["WBAJA7105LB123456", "WBAJA7105LB654321"],
"file_name": "batch-1.csv",
"bulk_id": null
}Response example
{
"task_state": "pending",
"task_ids": ["task_abc", "task_def"],
"success": true,
"message": "Vin bulk decode task started"
}PUT/api/v1/decode/{user_id}/bulk/{bulk_id}/pause
Authentication: Bearer token (How to get a token)
Request schema
Headers
Description
Authorization
Bearer <token>
Response schema
Field
Description
success
boolean
message
string
Request example
PUT /api/v1/decode/usr_xxx/bulk/42/pause
Authorization: Bearer <token>Response example
{
"success": true,
"message": "Bulk decode task paused"
}GET/api/v1/decode/{user_id}/tasks/{task_id}
Authentication: Bearer token (How to get a token)
Request schema
Headers
Description
Authorization
Bearer <token>
Response schema
Field
Description
results (object | null
final, intermediate)
success
boolean
message
string | null
Request example
GET /api/v1/decode/usr_xxx/tasks/task_abc
Authorization: Bearer <token>Response example
{
"results": {
"final": null,
"intermediate": null
},
"success": true,
"message": "Task in progress"
}VAG Map API
Base path: /api/v1/vag-map
POST/api/v1/vag-map/map
Authentication: Bearer token (optional) (How to get a token)
Request schema
Body
Description
brand
string (optional, default VAG)
report_id
integer | null (optional)
report
object | null (optional)
vin
string | null (optional)
make
string | null (optional)
model
string | null (optional)
Validation rules
- exactly one of report_id or report is required
Response schema
Field
Description
brand
string
payload
array of { category, filter, value }
success
boolean
message
string | null
Notes: If report_id is provided, source report is loaded from vin_lookups. HTTP 422 is returned when report mapping fails validation (REPORT_FORMAT_ERROR), for example when report tab labels/structure do not match expected format.
Request example
POST /api/v1/vag-map/map
Content-Type: application/json
{
"brand": "VAG",
"report": {
"0": {
"tab_name": "Identification",
"data": [["Model", "Golf"]]
}
},
"vin": "WVWZZZ1KZ6W000001",
"make": "Volkswagen",
"model": "Golf"
}Response example
{
"brand": "VAG",
"payload": [
{ "category": "Model", "filter": "model", "value": "Golf" }
],
"success": true,
"message": null
}Error Codes
- 400 Bad Request - Invalid request payload or required input missing.
- 401 Unauthorized - Invalid or missing bearer token.
- 403 Forbidden - Authenticated but not allowed for the requested resource.
- 404 Not Found - Resource does not exist (for example, lookup not found).
- 422 Unprocessable Entity - Validation or mapping format error (for example REPORT_FORMAT_ERROR).
- 500 Internal Server Error - Unexpected backend error.