> ## Documentation Index > Fetch the complete documentation index at: https://docsv4.mile.app/llms.txt > Use this file to discover all available pages before exploring further. # Vehicle Maintenance > A vehicle maintenance schedule is a period during which a vehicle is left out of route optimization ## What is a Vehicle Maintenance Schedule? A vehicle maintenance schedule is a period, with a start and an end time, during which a vehicle is in the workshop. While a schedule covers the routing date, the vehicle is left out of route optimization. A vehicle can have as many schedules as needed, and each one can carry an optional note. Two schedules of the same vehicle may not overlap. Schedules are their own resource, separate from the vehicle. The vehicle endpoints don't accept maintenance dates. **Related Guide:** [Vehicle Maintenance](https://docsv4.mile.app/pages/planning/routing/vehicle/vehicle-maintenance.md) ## Key Features > [card] [Read vehicle maintenance schedules](https://docsv4.mile.app/api-reference/routing/vehicle-maintenance/read-vehicle-maintenance-schedules.md) > > GET /vehicle-maintenances > [card] [Save vehicle maintenance schedules](https://docsv4.mile.app/api-reference/routing/vehicle-maintenance/save-vehicle-maintenance-schedules.md) > > POST /vehicle-maintenances > [card] [Delete vehicle maintenance schedule by ID](https://docsv4.mile.app/api-reference/routing/vehicle-maintenance/delete-vehicle-maintenance-schedule-by-id.md) > > DELETE /vehicle-maintenance/{id} ## Permissions These endpoints use the same Bearer token as the other routing endpoints and the existing vehicle permissions. There is no separate maintenance permission. A call without the permission answers `403` with the `sys-035` code. | Endpoint | Permission | | - | - | | `GET /vehicle-maintenances` | `view/vehicle` | | `POST /vehicle-maintenances` | `edit/vehicle` | | `DELETE /vehicle-maintenance/{id}` | `edit/vehicle` | Schedules are scoped to your organization. A schedule of another organization is reported as not found. ## Reading Schedules `GET /vehicle-maintenances` needs `hubId` or `vehicleId`. Without either it answers `400` with `vehic-001`. | Parameter | Effect | | - | - | | `startTime` | Keeps the schedules that end at or after this time. | | `endTime` | Keeps the schedules that start at or before this time. Not earlier than `startTime`. | | `isLatest` | `true` or `1` returns only the schedule that ended most recently. `page`, `limit` and `sortOrder` are ignored, and `total` is `0` or `1`. | | `sortOrder` | `asc` (default) or `desc`, by `startTime`. | | `limit` / `page` | 1 to 1000 per page (default 20), from page 1. | `startTime` and `endTime` accept `Y-m-d H:i:s`, read as UTC, or ISO-8601 with an offset, such as `2026-11-01T00:00:00+07:00`. With both, the list holds every schedule that overlaps the range. ``` GET /vehicle-maintenances?hubId={hubId}&startTime=2026-11-01T00:00:00+07:00&endTime=2026-11-30T23:59:59+07:00 GET /vehicle-maintenances?vehicleId={vehicleId}&isLatest=true ``` ## Saving Schedules `POST /vehicle-maintenances` creates, updates and deletes schedules in one request. Each entry in `data` needs `vehicleId`, `startTime` and `endTime`, and may carry `notes` (up to 500 characters). An entry with `_id` updates that schedule; one without `_id` creates a new schedule. `deletedIds` lists schedules to delete in the same request. `data` takes 1 to 1000 entries and `deletedIds` up to 1000. 1. **Nothing is saved unless everything passes.** Every entry is checked before the first write, so a rejected request leaves your data as it was. Messages name the entry by its position in `data`, starting at 1. 2. **The end must be later than the start.** 3. **No overlap.** Two schedules of the same vehicle overlap when each starts before the other ends. This is checked against saved schedules and against the other entries of the same request. A schedule may start exactly when another one ends. 4. **Ended schedules are read-only.** A schedule whose end time has passed can't be changed or deleted. Sending it back unchanged is accepted and leaves it as it is. 5. **Past entries are allowed.** A new entry may lie entirely in the past, to record a service that already happened. Times are stored in UTC and returned with a `+00:00` offset. ## Effect on Route Optimization `POST /routing` and `POST /route-optimization` accept `routingDate` (`YYYY-MM-DD`) and `timezone` (an IANA name such as `Asia/Jakarta`, the default). A vehicle with a schedule that covers the routing date is left out of the optimization, unless it is forced active with `isMaintenanceIgnore: true` on the vehicle. * The whole calendar day counts, in the request's `timezone`, including the first and last day of the schedule. The hours are ignored. * A schedule that has already ended no longer leaves the vehicle out. * Without `routingDate`, no vehicle is left out for maintenance. * When every vehicle in the request is left out, the request is rejected with `400` and `route-032`: *Every vehicle in this request is under maintenance on the routing date. Remove the schedule or force one of them active before optimizing.* * An unknown `timezone` is rejected with `400` and `route-008`. A [routing schedule](https://docsv4.mile.app/api-reference/routing/routing-schedule-overview.md) applies the same rule on the day it runs. When every vehicle of its profile is under maintenance, the run is skipped with the reason `no_vehicle`. ## Vehicle Fields The [vehicle object](https://docsv4.mile.app/api-reference/objects/vehicle-object.md) carries three related fields: | Field | Meaning | | - | - | | `statusMaintenance` | `maintenance` while a schedule is running, `scheduled` when one starts within 24 hours, otherwise `null`. Maintained by the system; treat it as read-only. | | `isMaintenanceIgnore` | `true` when the vehicle is forced active and used in optimization while under maintenance. Set it with `PATCH /vehicle/{vehicleId}`. The system clears it once the vehicle has no schedule left that has not ended. | | `isActive` | Records whether the vehicle's switch is on in the routing configuration. | `POST /vehicle`, `POST /vehicles/`, `PUT /vehicle/{vehicleId}` and `PATCH /vehicle/{vehicleId}` reject `maintenanceStartTime` and `maintenanceEndTime` with `400` and `vehic-042`. Record maintenance periods with `POST /vehicle-maintenances` instead. Deleting a vehicle also permanently deletes its maintenance schedules. ## Errors | Condition | HTTP | `failedCode` | | - | - | - | | Neither `hubId` nor `vehicleId` on a read | 400 | `vehic-001` | | Invalid read parameter, or `endTime` earlier than `startTime` | 400 | `vehic-003` | | `data` missing or empty, or an entry without `vehicleId`, `startTime` or `endTime` | 400 | `vehic-001` | | `data` or `deletedIds` not an array | 400 | `vehic-011` | | More than 1000 entries, or `notes` longer than 500 characters | 400 | `vehic-009` | | A `deletedIds` entry, or `notes`, that is not a string | 400 | `vehic-016` | | The vehicle of an entry was not found | 400 | `vehic-033` | | A date that can't be read, or an end not later than the start | 400 | `vehic-003` | | An `_id` or `deletedIds` entry, or the `{id}` of a delete, that doesn't exist | 404 | `vehic-043` | | An ended schedule changed or deleted | 400 | `vehic-044` | | An entry overlaps a saved schedule or another entry of the request | 400 | `vehic-041` | | `maintenanceStartTime` / `maintenanceEndTime` sent to a vehicle endpoint | 400 | `vehic-042` | | The caller lacks the vehicle permission | 403 | `sys-035` | ## Related Resources * [Vehicle](https://docsv4.mile.app/api-reference/routing/vehicle-overview.md) - The vehicles these schedules belong to * [Vehicle Object](https://docsv4.mile.app/api-reference/objects/vehicle-object.md) - Vehicle data structure * [Routing](https://docsv4.mile.app/api-reference/routing/overview.md) - Route optimization, which leaves out vehicles under maintenance This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.