Maintenance - Fleet Management System

The Maintenance API is split into two areas:

Maintenance types — admin-only CRUD for the catalog of maintenance categories.
Vehicle maintenance — assign maintenance to vehicles, query status, and mark items as complete.

Maintenance types

Maintenance types form the catalog used when assigning preventive maintenance to a vehicle.

All maintenance type endpoints require an admin role.

List maintenance types

GET /api/admin/maintenance-types Returns all maintenance types ordered alphabetically by name.

Response

maintenanceTypes

object[]

Show Maintenance type properties

number

Unique maintenance type ID.

name

string

Type name (unique).

description

string

Optional description.

isActive

boolean

Whether this type is active. Defaults to true.

created_at

string

ISO 8601 creation timestamp.

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/maintenance-types \
  --header 'Authorization: Bearer <token>'

Create maintenance type

POST /api/admin/maintenance-types Creates a new maintenance type.

Request body

name

string

required

Type name. Must be unique.

description

string

Optional description of what this maintenance type covers.

isActive

boolean

default:"true"

Whether this maintenance type is currently active. Inactive types remain in the catalog but can be filtered out. Defaults to true.

Response

Returns 201 Created with the new maintenance type object.

maintenanceType

object

Created maintenance type.

Errors

Status	Description
`400`	Validation failed — `name` is missing.
`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/maintenance-types \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Oil Change",
    "description": "Engine oil and filter replacement"
  }'

Update maintenance type

PUT /api/admin/maintenance-types/:id Updates a maintenance type’s name or description.

Path parameters

number

required

The maintenance type ID.

Request body

name

string

required

Updated type name.

description

string

Updated description.

isActive

boolean

Set to false to deactivate this maintenance type.

Response

Returns 200 OK with the updated maintenance type.

maintenanceType

object

Updated maintenance type.

Errors

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

Delete maintenance type

DELETE /api/admin/maintenance-types/:id Permanently deletes a maintenance type.

Path parameters

number

required

The maintenance type 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`	Maintenance type not found.
`500`	Internal server error.

Vehicle maintenance

Assign maintenance to vehicle

POST /api/admin/vehicles/:vehicleId/maintenance Assigns a maintenance record to a vehicle. Supports two modes:

Preventive — linked to a maintenance type, tracks the last service and schedules the next.
Mandatory — not linked to a type, blocks inspections until completed.

Requires the admin role.

Path parameters

vehicleId

number

required

The vehicle ID.

Request body

isPreventive

boolean

required

true for preventive maintenance, false for mandatory maintenance.

maintenanceTypeId

number

ID of the maintenance type. Required when isPreventive is true.

lastPerformedDate

string

Date the maintenance was last performed (YYYY-MM-DD). Used when isPreventive is true.

lastPerformedMileage

number

Odometer reading at last service. Used when isPreventive is true. Defaults to 0.

nextDueDate

string

Date the maintenance is next due (YYYY-MM-DD).

nextDueMileage

number

Odometer reading at which maintenance is next due.

Response

Returns 201 Created with the new maintenance record.

maintenance

object

Show Vehicle maintenance record

number

Record ID.

vehicleId

number

Vehicle ID.

maintenanceTypeId

number

Maintenance type ID (preventive only).

isPreventive

boolean

Whether this is a preventive maintenance item.

lastPerformedDate

string

Date of last service (YYYY-MM-DD).

lastPerformedMileage

number

Mileage at last service.

nextDueDate

string

Next due date (YYYY-MM-DD).

nextDueMileage

number

Mileage threshold for next service.

assignedByAdminId

number

ID of the admin who created this record.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last update timestamp.

Errors

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

curl --request POST \
  --url https://your-api.example.com/api/admin/vehicles/42/maintenance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "isPreventive": true,
    "maintenanceTypeId": 1,
    "lastPerformedDate": "2024-01-01",
    "lastPerformedMileage": 10000,
    "nextDueDate": "2024-07-01",
    "nextDueMileage": 15000
  }'

Remove vehicle maintenance record

DELETE /api/admin/vehicle-maintenance/:id Permanently removes a maintenance record from a vehicle.

Requires the admin role.

Path parameters

number

required

The vehicle maintenance record 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`	Maintenance record not found.
`500`	Internal server error.

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

Get vehicle maintenance status

GET /api/vehicles/:vehicleId/maintenance/status Returns the maintenance status for a vehicle. Optionally pass the current mileage to get mileage-based overdue calculations. Requires a valid JWT. No admin role restriction — technicians and admins may both call this endpoint.

Path parameters

vehicleId

number

required

The vehicle ID.

Query parameters

currentMileage

number

Current odometer reading. When provided, the response includes mileage-based overdue checks for preventive maintenance items.

Response

status

object

Show Maintenance status properties

preventive

object

Summary of all preventive maintenance items and their due status.

mandatory

object

Show Mandatory maintenance summary

requiresAttention

boolean

true if any mandatory item is overdue by date or mileage.

items

object[]

List of mandatory maintenance items.

Errors

Status	Description
`401`	Missing or invalid JWT.
`404`	Vehicle not found.
`500`	Internal server error.

curl --request GET \
  --url 'https://your-api.example.com/api/vehicles/42/maintenance/status?currentMileage=15230' \
  --header 'Authorization: Bearer <token>'

Complete maintenance

POST /api/vehicles/:vehicleId/maintenance/complete Marks a maintenance item as completed for a vehicle, updating lastPerformedDate and lastPerformedMileage. Requires a valid JWT and the technician or admin role.

Path parameters

vehicleId

number

required

The vehicle ID.

Request body

completedDate

string

required

Date the maintenance was completed (YYYY-MM-DD ISO 8601 format).

completedMileage

number

required

Odometer reading at time of completion (non-negative integer).

maintenanceId

number

ID of the specific VehicleMaintenance record to mark complete. If omitted, isPreventive must be provided so the system can find or create the record.

isPreventive

boolean

Required when maintenanceId is not provided. true for preventive, false for mandatory.

maintenanceTypeId

number

Maintenance type ID. Used when isPreventive is true and maintenanceId is not provided.

workshopSuggestedDate

string

Workshop-suggested next due date (YYYY-MM-DD). Overrides the stored nextDueDate if provided.

completionNotes

string

Free-text notes about the completion (e.g., parts replaced, observations).

Response

Returns 200 OK with the updated maintenance record.

maintenance

object

Updated vehicle maintenance record with refreshed lastPerformedDate, lastPerformedMileage, and updated_at.

Errors

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

curl --request POST \
  --url https://your-api.example.com/api/vehicles/42/maintenance/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "maintenanceId": 9,
    "completedDate": "2024-01-15",
    "completedMileage": 15230,
    "completionNotes": "Oil and filter replaced"
  }'

Authentication

Resources

​Maintenance types

​List maintenance types

​Response

​Errors

​Create maintenance type

​Request body

​Response

​Errors

​Update maintenance type

​Path parameters

​Request body

​Response

​Errors

​Delete maintenance type

​Path parameters

​Response

​Errors

​Vehicle maintenance

​Assign maintenance to vehicle

​Path parameters

​Request body

​Response

​Errors

​Remove vehicle maintenance record

​Path parameters

​Response

​Errors

​Get vehicle maintenance status

​Path parameters

​Query parameters

​Response

​Errors

​Complete maintenance

​Path parameters

​Request body

​Response

​Errors

Build docs developers (and LLMs) love

Maintenance types

List maintenance types

Response

Errors

Create maintenance type

Request body

Response

Errors

Update maintenance type

Path parameters

Request body

Response

Errors

Delete maintenance type

Path parameters

Response

Errors

Vehicle maintenance

Assign maintenance to vehicle

Path parameters

Request body

Response

Errors

Remove vehicle maintenance record

Path parameters

Response

Errors

Get vehicle maintenance status

Path parameters

Query parameters

Response

Errors

Complete maintenance

Path parameters

Request body

Response

Errors