---
title: "Update Vehicle by ID"
method: PUT
path: "/vehicles/{id}"
tags: ["Vehicles"]
---

# Update Vehicle by ID

`PUT /vehicles/{id}`

## Request

- Base URL: `https://api.smartroutes.io/v2`
- URL: `https://api.smartroutes.io/v2/vehicles/{id}`
- Auth: none declared

Updates one vehicle in your depot. This is a partial update: only the fields you send change. The same rules as `POST /vehicles` apply to the fields you do send. For example, switching `start_location` to `other` requires `start_lat` and `start_lng` in the same request, and setting `break: true` requires the break times and duration. Sending `capacities` or `skills` replaces the vehicle's whole set (an empty array clears it), and leaving them out keeps the existing set.

Changes to `availability`, shift times and `break` are applied to the vehicle's default shift. If the vehicle has a per-day or multi-shift schedule set up in the SmartRoutes web app, that schedule is left unchanged. The updated vehicle is returned under `vehicle`. An `id` that doesn't belong to a vehicle in your depot returns `400 INVALID_INPUT`.

## Path parameters

- `id` number, required

## Request body

- object: Request body for updating a vehicle.
  - `name` string: Name of the vehicle.
  - `availability` 'shift' | 'full_day' | 'always', required: Availability status of the vehicle.
  - `shift_start` string, time, nullable: Start time of the vehicle's shift (if availability is 'shift').
  - `shift_end` string, time, nullable: End time of the vehicle's shift (if availability is 'shift').
  - `start_location` 'depot' | 'other' | 'app-location', required: Location type where the vehicle starts.
  - `start_address` string, nullable: Address where the vehicle starts (if location is 'other').
  - `start_lng` number, nullable: Longitude of the starting location (if location is 'other').
  - `start_lat` number, nullable: Latitude of the starting location (if location is 'other').
  - `end_location` 'depot' | 'other' | 'none', required: Location type where the vehicle ends.
  - `end_address` string, nullable: Address where the vehicle ends (if location is 'other').
  - `end_lng` number, nullable: Longitude of the ending location (if location is 'other').
  - `end_lat` number, nullable: Latitude of the ending location (if location is 'other').
  - `break` boolean: Flag indicating whether the vehicle has a break.
  - `break_start` string, time, nullable: Start time of the vehicle's break (if it has a break).
  - `break_end` string, time, nullable: End time of the vehicle's break (if it has a break).
  - `break_duration` number, nullable: Duration of the vehicle's break in minutes (if it has a break).
  - `active` boolean: Flag indicating whether the vehicle is active.
  - `skills` string[]: Array of skills associated with the vehicle.
  - `capacities` object[]: Array of capacities associated with the vehicle.
    - `id` integer, required: Id of capacity (e.g., 1, 2).
    - `capacity` number, float, required: Capacity value for the specified type.

## Response `200`

Successful response

- VehicleResponse
  - `vehicle` Vehicle, required: A depot vehicle. Property set is the union of fields returned by list and get-by-id paths; conditional fields (shift_*, start_address/lat/lng, end_address/lat/lng, break_*) populate only when the corresponding mode is selected. Source of truth: `getExternalModel` in `src/vehicles/vehicles.service.js`.
    - `id` integer
    - `name` string
    - `active` boolean
    - `availability` 'shift' | 'full_day' | 'always'
    - `start_location` 'depot' | 'other' | 'app-location'
    - `end_location` 'depot' | 'other' | 'none'
    - `capacities` object[]
      - `id` integer
      - `type` string
      - `capacity` number
    - `skills` string[]
    - `shift` object[]: Weekly shift schedule. Each entry is one row of vehicle_shifts (enabled, availability, shift_start, shift_end, force_shift_start, max_route_duration, day_of_week) plus a nested vehicle_breaks array.
      - `enabled` boolean
      - `availability` 'shift' | 'full_day' | 'always'
      - `shift_start` string, nullable: HH:mm.
      - `shift_end` string, nullable: HH:mm.
      - `force_shift_start` boolean
      - `max_route_duration` integer, nullable: Minutes.
      - `day_of_week` 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY' | 'SUNDAY' | 'null', nullable
      - `vehicle_breaks` object[]
        - `enabled` boolean
        - `break_start` string, nullable: HH:mm.
        - `break_end` string, nullable: HH:mm.
        - `break_duration` integer, nullable: Minutes.
    - `created` string, date-time
    - `updated` string, date-time
    - `shift_start` string, nullable: HH:mm. Present when availability == 'shift'.
    - `shift_end` string, nullable: HH:mm. Present when availability == 'shift'.
    - `start_address` string, nullable: Present when start_location == 'other'.
    - `start_lat` number, nullable
    - `start_lng` number, nullable
    - `end_address` string, nullable: Present when end_location == 'other'.
    - `end_lat` number, nullable
    - `end_lng` number, nullable
    - `break` boolean
    - `break_start` string, nullable: HH:mm. Present when break == true.
    - `break_end` string, nullable: HH:mm. Present when break == true.
    - `break_duration` number, nullable: Minutes. Present when break == true.

## Other responses

- `400`: Invalid input. The request body failed validation.
- `403`: Forbidden. Returned for rate-limit exhaustion (`name = FORBIDDEN`, with `details.retry_after_seconds` and `Retry-After` header) and permission gate failures (`name = PERMISSION`). Inspect `name` to disambiguate. Send `x-sr-api-features: rate-limit-429` to receive `429 RATE_LIMIT_EXCEEDED` for the rate-limit case instead, leaving `403` to mean permission failures only — see [API Features](#section/Getting-started/API-Features).
- `404`: The requested resource was not found.
- `429`: Rate limit exceeded (`name = RATE_LIMIT_EXCEEDED`). **Only returned to callers that opt in** with the `x-sr-api-features: rate-limit-429` request header; without it the same condition returns `403` with `name = FORBIDDEN` and an otherwise identical body. See [API Features](#section/Getting-started/API-Features).
- `500`: An unexpected server error occurred. The body carries only `name` and `description`: internal details are never returned.

---

[API](https://skmtc.dev/smartroutes/apis/smartroutes-api.md) · [All operations](https://skmtc.dev/smartroutes/apis/smartroutes-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smartroutes/apis/smartroutes-api/revisions/a7ea507afac7?raw)