> ## 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. # Save vehicle maintenance schedules > Creates, updates and deletes maintenance schedules in one request. `data` holds the schedules to create or update, and `deletedIds` the schedules to delete permanently. **All or nothing.** Every entry is checked before anything is written, so a rejected request saves nothing. Error messages name the entry by its position in `data`, starting at 1 (for example `Entry 2 ...`). **Overlap.** Two schedules of the same vehicle may not overlap, neither with a saved schedule nor with another entry of the same request. A schedule may start exactly when another one ends. **Ended schedules are read-only.** A schedule whose end time has passed cannot be changed or deleted. Sending it back unchanged is accepted and leaves it as it is. A new entry may lie in the past, to record a service that already happened. **Errors.** `vehic-001` `data` missing or empty, or an entry without `vehicleId`, `startTime` or `endTime`; `vehic-011` `data` or `deletedIds` is not an array; `vehic-009` more than 1000 entries, or `notes` longer than 500 characters; `vehic-016` a `deletedIds` entry or `notes` that is not a string; `vehic-033` the vehicle was not found; `vehic-003` a date that cannot be read, or an end that is not later than the start; `vehic-043` (404) an `_id` or `deletedIds` entry that does not exist; `vehic-044` an ended schedule changed or deleted; `vehic-041` an overlap. Requires the **Edit Vehicle** permission. ## OpenAPI ````yaml /openapi/public/openapi-routing.json post /vehicle-maintenances openapi: 3.0.0 info: title: API - Routing version: 3.0.0 description: API Documentation - RESTful API for field operations management. servers: - url: https://apiweb.mile.app/api/v3 security: - bearerAuth: [] tags: - name: Vehicle description: >- The vehicle represents a car, bike, truck, or other form of transportation used in your organization. They are utilized to optimize the route planning process, determining the most efficient path for completing multiple tasks or visits. The vehicle attributes contain IDs, capacity, speed, working hours, tags, and constraints. **To see the details of vehicle object, please follow [this link](#tag/vehicle_model)** - name: Vehicle Maintenance description: >- A vehicle maintenance schedule is a period during which a vehicle is in the workshop and is left out of route optimization. A vehicle can have as many schedules as needed; two schedules of the same vehicle may not overlap. **Related Guide:** [Vehicle Maintenance](/pages/planning/routing/configuration/vehicle-maintenance) - name: Routing description: >- The **Routing** refers to process of finding the most effective routes for vehicles to travel from one visit to another. The optimization process will generate a result that could update the respective task data when dispatched. With the ability to handle complex constraints and variables such as capacity, time windows, and vehicle availability, the API can be customized to meet the specific needs of any business or organization. **This section is for the v2 of routing api, if you still use the old one, please follow [this link](/v1) to see documentation**. **Routing results** are collection of route optimization's results that already successfully processed and saved in the database. Routing results contains list of routed visits and dropped visits. 1. Routed visits are sequence recommendation of visits/tasks list according to most suitable vehicle and best route. 2. Dropped visits are list of tasks/visits that out of range of the calculation. **To see the details of routing object, please follow [this link](#tag/route_model)** ## Why use Route Optimization With Route Optimization API, you can establish or refine an automated dispatch or route planning process that improves the operational efficiency of your transportation needs. With parameters to express your unique operational objectives and constraints, and an algorithm built on top of the trusted Google Maps data, the service generates the best possible route plans to meet those constraints. Some use-case examples follow: - A **logistics company** uses Route Optimization to optimize the assignments of all next-day shipments, providing a route for each shipment that optimizes for distance and time efficiency, cost saving, on time delivery, and driver and end customer satisfaction. - A **field service provider** uses Route Optimization to find the optimal route and sequence for technician's service appointments, and re-optimize when condition changes occur, such as en route delays. - An **on demand food delivery** company uses Route Optimization in their real-time dispatch process to choose the best active driver to pick up several new orders and insert it in their existing routes. - A **medical service provider** uses Route Optimization to map health providers to appointments, improving the efficiency of the routes for each provider across their day. ## How Route Optimization works The Route Optimization API uses a number of inputs to return a route plan. Inputs include vehicles, visits or shipments, configurations, and constraints. A route plan includes tasks assignment to vehicles, the multi-stop routes for each vehicle, and the related metrics. - name: Routing Schedule description: >- A Routing Schedule runs route optimization automatically at the times you set, without anyone opening the app. Each schedule points at one Configuration Profile, which supplies the hub and the vehicles for every run. When Auto Dispatch is enabled, the optimized routes are dispatched to the field users as soon as the optimization finishes. **Related Guide:** [Routing Schedule](/pages/route-optimization/schedule/introduction) - name: Configuration description: >- Configuration endpoints for managing routing and optimization settings including time windows, constraints, and optimization parameters. - name: Capacity Constraint description: >- Capacity Constraint endpoints for managing vehicle capacity constraints in route optimization. Define weight, volume, and other capacity limits for vehicles. - name: Geotagging description: Geotagging endpoints for location tagging and geographic data management. paths: /vehicle-maintenances: post: tags: - Vehicle Maintenance summary: Save vehicle maintenance schedules description: >- Creates, updates and deletes maintenance schedules in one request. `data` holds the schedules to create or update, and `deletedIds` the schedules to delete permanently. **All or nothing.** Every entry is checked before anything is written, so a rejected request saves nothing. Error messages name the entry by its position in `data`, starting at 1 (for example `Entry 2 ...`). **Overlap.** Two schedules of the same vehicle may not overlap, neither with a saved schedule nor with another entry of the same request. A schedule may start exactly when another one ends. **Ended schedules are read-only.** A schedule whose end time has passed cannot be changed or deleted. Sending it back unchanged is accepted and leaves it as it is. A new entry may lie in the past, to record a service that already happened. **Errors.** `vehic-001` `data` missing or empty, or an entry without `vehicleId`, `startTime` or `endTime`; `vehic-011` `data` or `deletedIds` is not an array; `vehic-009` more than 1000 entries, or `notes` longer than 500 characters; `vehic-016` a `deletedIds` entry or `notes` that is not a string; `vehic-033` the vehicle was not found; `vehic-003` a date that cannot be read, or an end that is not later than the start; `vehic-043` (404) an `_id` or `deletedIds` entry that does not exist; `vehic-044` an ended schedule changed or deleted; `vehic-041` an overlap. Requires the **Edit Vehicle** permission. operationId: saveVehicleMaintenances requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/POSTVehicleMaintenancesRequestSave' responses: '200': description: Success content: application/json: schema: type: object properties: status: type: boolean description: Shows if the request was successful. data: type: array items: $ref: '#/components/schemas/VehicleMaintenanceSchedule' description: >- The saved schedules, in the same order as `data` in the request. example: status: true data: - _id: 6720a1f0c2e4b0a1000112ab organizationId: 65a1b2c3d4e5f60000000001 vehicleId: 65f9c1aa77e0b30001aa1122 hubId: 65e7b0110000000000000001 startTime: '2026-11-04T01:00:00+00:00' endTime: '2026-11-04T10:00:00+00:00' notes: Annual service createdBy: planner@example.com createdTime: '2026-10-29T03:12:44+00:00' updatedTime: '2026-10-29T03:12:44+00:00' '400': description: Bad Request content: application/json: schema: type: object properties: status: type: boolean description: Shows if the request was successful. message: type: string description: A short message explaining what went wrong. failedCode: type: string description: Error code that identifies the failure. examples: missingData: value: status: false message: Send at least one maintenance schedule entry. failedCode: vehic-001 incompleteEntry: value: status: false message: >- Entry 1 is incomplete. A maintenance schedule needs a vehicle, a start date and an end date. Nothing was saved. failedCode: vehic-001 notAnArray: value: status: false message: Send at least one maintenance schedule entry. failedCode: vehic-011 notesTooLong: value: status: false message: Notes can be at most 500 characters. Nothing was saved. failedCode: vehic-009 vehicleNotFound: value: status: false message: The vehicle in entry 1 was not found. Nothing was saved. failedCode: vehic-033 invalidDate: value: status: false message: >- Entry 1 has an invalid date. Please use a full date and time. Nothing was saved. failedCode: vehic-003 endBeforeStart: value: status: false message: Entry 1 must end later than it starts. Nothing was saved. failedCode: vehic-003 endedSchedule: value: status: false message: >- Schedules that have already ended cannot be changed or deleted. Nothing was saved. failedCode: vehic-044 overlapSaved: value: status: false message: >- Entry 1 overlaps a saved maintenance schedule for vehicle B 1234 XY. Nothing was saved. failedCode: vehic-041 overlapPayload: value: status: false message: >- Entry 2 overlaps another entry in this form for vehicle B 1234 XY. Nothing was saved. failedCode: vehic-041 '403': description: Forbidden content: application/json: schema: type: object properties: status: type: boolean description: Shows if the request was successful. message: type: string description: A short message explaining what went wrong. failedCode: type: string description: Error code that identifies the failure. examples: forbidden: value: status: false message: >- Access denied. You do not have permission for edit vehicle. Please contact your admin to request access. failedCode: sys-035 '404': description: Schedule not found content: application/json: schema: type: object properties: status: type: boolean description: Shows if the request was successful. message: type: string description: A short message explaining what went wrong. failedCode: type: string description: Error code that identifies the failure. examples: notFound: value: status: false message: Maintenance schedule not found. failedCode: vehic-043 security: - bearerAuth: [] components: schemas: POSTVehicleMaintenancesRequestSave: type: object required: - data properties: data: type: array minItems: 1 maxItems: 1000 description: >- The schedules to create or update, 1 to 1000 entries. An entry with `_id` updates that schedule; an entry without `_id` creates a new one. items: type: object required: - vehicleId - startTime - endTime properties: _id: type: string description: >- Identifier of an existing schedule to update. Leave it out to create a new schedule. **Example:** `6720a1f0c2e4b0a1000112ab` vehicleId: type: string description: >- The vehicle the period belongs to. It must exist in your organization. **Example:** `65f9c1aa77e0b30001aa1122` startTime: type: string description: >- Start of the period. Send ISO-8601 with an offset; a value without an offset is read as UTC. **Example:** `2026-11-04T08:00:00+07:00` endTime: type: string description: >- End of the period, same format. Must be later than `startTime`. **Example:** `2026-11-04T17:00:00+07:00` notes: type: string nullable: true maxLength: 500 description: >- Optional note, at most 500 characters. Trimmed; a blank or missing value is stored as `null`, so leaving it out of an update clears the note. **Example:** `Annual service` deletedIds: type: array maxItems: 1000 items: type: string description: >- Identifiers of schedules to delete permanently in the same request, at most 1000. example: data: - vehicleId: 65f9c1aa77e0b30001aa1122 startTime: '2026-11-04T08:00:00+07:00' endTime: '2026-11-04T17:00:00+07:00' notes: Annual service - _id: 6720a1f0c2e4b0a1000112ab vehicleId: 65f9c1aa77e0b30001aa1133 startTime: '2026-11-06T08:00:00+07:00' endTime: '2026-11-07T17:00:00+07:00' notes: null deletedIds: - 6720a1f0c2e4b0a1000112cd VehicleMaintenanceSchedule: type: object properties: _id: type: string description: >- Unique identifier of the maintenance schedule, generated by the system. organizationId: type: string description: >- Organization the schedule belongs to. Always taken from the access token. vehicleId: type: string description: The vehicle this period belongs to. hubId: type: string description: >- Hub of the vehicle, copied from the vehicle each time the schedule is saved. startTime: type: string description: Start of the period, ISO-8601 in UTC (`+00:00`). endTime: type: string description: >- End of the period, ISO-8601 in UTC (`+00:00`). Always later than `startTime`. notes: type: string nullable: true description: Free-text note, trimmed. `null` when no note was recorded. createdBy: type: string description: Email address of the user who created the schedule. createdTime: type: string description: When the schedule was created, ISO-8601 in UTC. updatedTime: type: string description: When the schedule was last changed, ISO-8601 in UTC. example: _id: 6720a1f0c2e4b0a1000112ab organizationId: 65a1b2c3d4e5f60000000001 vehicleId: 65f9c1aa77e0b30001aa1122 hubId: 65e7b0110000000000000001 startTime: '2026-11-04T01:00:00+00:00' endTime: '2026-11-04T10:00:00+00:00' notes: Annual service createdBy: planner@example.com createdTime: '2026-10-29T03:12:44+00:00' updatedTime: '2026-10-29T03:12:44+00:00' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Use a valid Bearer token to authenticate. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.