Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

The Maintenance API gives fleet managers a first-class way to schedule and track vehicle servicing events. When a maintenance window is created, the platform records it as a MaintenanceRecord and — critically — registers the vehicle’s unavailability for the entire window, so that the Vehicles availability search will not surface the vehicle to booking workflows during that period. This tight integration between the maintenance and availability subsystems prevents double-allocation: a vehicle cannot be booked while it is in the workshop. Maintenance records progress through three statuses: SCHEDULED (confirmed but not yet started), IN_PROGRESS (servicing is underway), and COMPLETED (work is done and the vehicle can be returned to active service). The single endpoint exposed here requires the vehicle.update permission, reflecting that scheduling maintenance is a mutation of vehicle state.

​
POST /vehicles/:id/maintenance

Schedules a new maintenance window for the specified vehicle. Required permission: vehicle.update
Scheduling maintenance immediately marks the vehicle as unavailable for the specified date range in the availability engine. Any attempt to book the vehicle for an overlapping period will return no results from GET /vehicles/search until the maintenance window ends or is resolved. Ensure the startDate and endDate are correct before submitting.

​
Path parameters

​
id
string
required
The UUID of the vehicle to schedule maintenance for. Must reference an existing vehicle.

​
Request body

​
startDate
string (ISO 8601)
required
The date and time at which the maintenance window begins. Must be a valid ISO 8601 date string (e.g., 2024-07-15T08:00:00.000Z). Validated with @IsDateString().
​
endDate
string (ISO 8601)
required
The date and time at which the maintenance window is expected to end. Must be a valid ISO 8601 date string (e.g., 2024-07-17T18:00:00.000Z). Must be after startDate. Validated with @IsDateString().
​
reason
string
required
A human-readable description of why the vehicle is being taken in for maintenance (e.g., "Scheduled 10,000 km service", "Brake pad replacement", "Annual fitness inspection"). Must be a non-empty string.

​
Response

Returns the newly created MaintenanceRecord object.
​
id
string
UUID primary key of the maintenance record, auto-generated.
​
vehicleId
string
UUID of the vehicle this maintenance record belongs to.
​
startDate
string (ISO 8601)
Start of the maintenance window, stored as a timezone-aware timestamp (timestamptz).
​
endDate
string (ISO 8601)
Expected end of the maintenance window, stored as a timezone-aware timestamp (timestamptz).
​
reason
string
The stated reason for the maintenance event.
​
status
MaintenanceStatus
Current lifecycle status of the maintenance record. Newly created records start at SCHEDULED.
​
createdAt
string (ISO 8601)
Timestamp of record creation, set automatically by the database.
​
updatedAt
string (ISO 8601)
Timestamp of the last update to this record, maintained automatically by the database.

​
Availability impact

Calling this endpoint causes the service layer to create a VehicleAvailability record covering the startDate–endDate window. This record is consulted by VehicleService.searchAvailable when answering GET /vehicles/search queries. Any search whose requested window overlaps with an active maintenance window will not include the affected vehicle in its results — regardless of whether the MaintenanceRecord status is SCHEDULED or IN_PROGRESS. The vehicle re-enters the available pool only once the maintenance status transitions to COMPLETED and the corresponding availability block is removed.
To inspect all maintenance records for a specific vehicle without going through the search endpoint, use the MaintenanceService.findByVehicle(vehicleId) method directly in the service layer. A dedicated HTTP endpoint for this query may be added in a future API version.

​
Example

curl -X POST http://localhost:3000/vehicles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/maintenance \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2024-07-15T08:00:00.000Z",
    "endDate": "2024-07-17T18:00:00.000Z",
    "reason": "Scheduled 10,000 km service and brake inspection"
  }'

{
  "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "vehicleId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "startDate": "2024-07-15T08:00:00.000Z",
  "endDate": "2024-07-17T18:00:00.000Z",
  "reason": "Scheduled 10,000 km service and brake inspection",
  "status": "SCHEDULED",
  "createdAt": "2024-06-20T10:30:00.000Z",
  "updatedAt": "2024-06-20T10:30:00.000Z"
}

​
Error cases

StatusReason
401 UnauthorizedMissing or expired Authorization bearer token.
403 ForbiddenAuthenticated principal lacks the vehicle.update permission.
400 Bad RequestValidation failure — e.g., startDate or endDate are not valid ISO 8601 date strings, or reason is missing.

Build docs developers (and LLMs) love

Get started for freeTalk to us