Vehicles

All vehicle endpoints are protected. Requests must include a valid JWT and the authenticated user must have the admin role.

Endpoints that accept file uploads (POST /api/admin/vehicles and PUT /api/admin/vehicles/:id) must use multipart/form-data encoding. All other endpoints accept application/json.

List vehicles

GET /api/admin/vehicles Returns all vehicles ordered by creation date (newest first). Use the optional fleetId query parameter to filter by fleet.

Query parameters

fleetId

number

Filter results to vehicles belonging to this fleet ID.

Response

vehicles

object[]

Show Vehicle properties

number

Unique vehicle ID.

fleetId

number

ID of the fleet this vehicle belongs to.

brand

string

Vehicle manufacturer (e.g., "Toyota").

model

string

Vehicle model name.

year

number

Model year.

licensePlate

string

License plate number (always uppercased).

licenseStatus

string

License status: active or expired.

odometerUnit

string

Odometer unit: km or mi.

maintenanceInterval

number

Distance between scheduled maintenance events (in the vehicle’s odometer unit). Defaults to 5000.

insuranceExpiry

string

Insurance expiry date in YYYY-MM-DD format.

insuranceDocUrl

string

Server path to the uploaded insurance document.

registrationDocUrl

string

Server path to the uploaded registration document.

created_at

string

ISO 8601 creation timestamp.

Fleet

object

Show Fleet properties

number

Fleet ID.

name

string

Fleet name.

Assignments

object[]

Active and historical assignments for this vehicle.

Inspections

object[]

Inspections recorded for this vehicle.

VehicleMaintenances

object[]

Maintenance records, each including a nested MaintenanceType.

Errors

Status	Description
`401`	Missing or invalid JWT.
`403`	Authenticated user does not have the `admin` role.
`500`	Internal server error.

curl --request GET \
  --url https://your-api.example.com/api/admin/vehicles \
  --header 'Authorization: Bearer <token>'

Create vehicle

POST /api/admin/vehicles Creates a new vehicle. Send the request as multipart/form-data to optionally attach document files.

Request body

brand

string

required

Vehicle manufacturer.

model

string

required

Vehicle model name.

licensePlate

string

required

License plate number. Stored in uppercase.

fleetId

number

required

ID of the fleet this vehicle belongs to.

year

number

Model year (e.g., 2023).

licenseStatus

string

default:"active"

License status. One of active or expired.

odometerUnit

string

default:"km"

Odometer unit. One of km or mi.

maintenanceInterval

number

default:"5000"

Distance between scheduled maintenance events.

insuranceExpiry

string

Insurance expiry date. Accepted formats: YYYY-MM-DD or DD-MM-YYYY.

insurance_doc

file

Insurance document file upload (multipart field name: insurance_doc).

registration_doc

file

Registration document file upload (multipart field name: registration_doc).

Response

Returns 201 Created with the new vehicle object.

vehicle

object

The created vehicle with all fields as described in List vehicles.

Errors

Status	Description
`400`	Validation failed — required fields missing or invalid values.
`401`	Missing or invalid JWT.
`403`	Authenticated user does not have the `admin` role.
`500`	Internal server error.

curl --request POST \
  --url https://your-api.example.com/api/admin/vehicles \
  --header 'Authorization: Bearer <token>' \
  --form 'brand=Toyota' \
  --form 'model=Hilux' \
  --form 'year=2023' \
  --form 'licensePlate=ABC-1234' \
  --form 'fleetId=1' \
  --form 'odometerUnit=km' \
  --form 'maintenanceInterval=5000' \
  --form 'insuranceExpiry=2025-12-31' \
  --form 'insurance_doc=@/path/to/insurance.pdf' \
  --form 'registration_doc=@/path/to/registration.pdf'

Get vehicle

GET /api/admin/vehicles/:id Returns a single vehicle by ID along with its current maintenance status.

Path parameters

number

required

The vehicle ID.

Response

vehicle

object

Vehicle object with the same shape as described in List vehicles.

maintenanceStatus

object

Show Maintenance status properties

preventive

object

Summary of preventive maintenance items.

mandatory

object

Show Mandatory maintenance

requiresAttention

boolean

true if any mandatory maintenance item is overdue.

Errors

Status	Description
`401`	Missing or invalid JWT.
`403`	Authenticated user does not have the `admin` role.
`404`	Vehicle not found.
`500`	Internal server error.

Update vehicle

PUT /api/admin/vehicles/:id Updates an existing vehicle. Send as multipart/form-data when uploading new document files. File fields are optional on update. If a file field is omitted, the existing stored URL is preserved. Pass an explicit empty string for insuranceDocUrl or registrationDocUrl in the body to clear the stored URL without uploading a new file.

Path parameters

number

required

The vehicle ID.

Request body

Accepts the same fields as Create vehicle. All fields are optional on update.

Response

Returns 200 OK with the updated vehicle object.

vehicle

object

Updated vehicle object.

Errors

Status	Description
`400`	Validation failed.
`401`	Missing or invalid JWT.
`403`	Authenticated user does not have the `admin` role.
`404`	Vehicle not found.
`500`	Internal server error.

Delete vehicle

DELETE /api/admin/vehicles/:id Permanently deletes a vehicle.

Path parameters

number

required

The vehicle ID.

Response

Returns 204 No Content on success with an empty body.

Errors

Status	Description
`401`	Missing or invalid JWT.
`403`	Authenticated user does not have the `admin` role.
`404`	Vehicle not found.
`500`	Internal server error.

curl --request DELETE \
  --url https://your-api.example.com/api/admin/vehicles/42 \
  --header 'Authorization: Bearer <token>'

Authentication

Resources

List vehicles

Query parameters

Response

Errors

Create vehicle

Request body

Response

Errors

Get vehicle

Path parameters

Response

Errors

Update vehicle

Path parameters

Request body

Response

Errors

Delete vehicle

Path parameters

Response

Errors

Build docs developers (and LLMs) love

Authentication

Resources

​List vehicles

​Query parameters

​Response

​Errors

​Create vehicle

​Request body

​Response

​Errors

​Get vehicle

​Path parameters

​Response

​Errors

​Update vehicle

​Path parameters

​Request body

​Response

​Errors

​Delete vehicle

​Path parameters

​Response

​Errors

Build docs developers (and LLMs) love

List vehicles

Query parameters

Response

Errors

Create vehicle

Request body

Response

Errors

Get vehicle

Path parameters

Response

Errors

Update vehicle

Path parameters

Request body

Response

Errors

Delete vehicle

Path parameters

Response

Errors