List Vehicles
# List Vehicles
Retrieves a list of vehicles registered on the platform, with optional filtering by `driverId` to fetch vehicles assigned to a specific driver.
---
### Endpoint Overview
- **Method:** `GET`
- **Route:** `/api/v1/vehicles`
- **Authentication:** `None (Public)`
- **Content-Type:** `N/A`
---
### Query Parameters
| Parameter | Data Type | Required | Default | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `driverId` | `string` | No | `null` | Prefixed with `drv_` | Filter to return only vehicles owned by this driver ID |
#### Example Request URLs
- GET {{baseUrl}}/api/v1/vehicles
- GET {{baseUrl}}/api/v1/vehicles?driverId=drv_8a7b6c5d4e
---
### Request Body Schema
_None (GET request)_
---
### Response Body Schema (`200 OK`)
| Top-Level Key | Data Type | Description |
| --- | --- | --- |
| `vehicles` | `array` | List of vehicle objects |
#### `Vehicle Item Fields`
| Field | Data Type | Nullable | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | No | Prefixed with `veh_` | Unique vehicle identifier |
| `driverId` | `string` | Yes | Prefixed with `drv_` | ID of associated driver (`null` if unlinked) |
| `name` | `string` | No | String | Vehicle make / brand |
| `model` | `string` | No | String | Vehicle model |
| `color` | `string` | Yes | String | Vehicle color |
| `number_plate` | `string` | Yes | String | Registration plate number |
| `created_at` | `string` | No | ISO 8601 Timestamp | Registration timestamp |
| `updated_at` | `string` | No | ISO 8601 Timestamp | Last update timestamp |
---
### `Response Examples`
#### ``1. `200 OK` — Vehicles Returned``
``` json
{
"vehicles": [
{
"id": "veh_1a2b3c4d5e",
"driverId": "drv_8a7b6c5d4e",
"name": "Maruti Suzuki",
"model": "Swift Dzire",
"color": "White",
"number_plate": "KA-01-AB-1234",
"created_at": "2026-09-21T05:40:00.000Z",
"updated_at": "2026-09-21T05:40:00.000Z"
}
]
}
```
#### ``2. `200 OK` — No Vehicles Found``
``` json
{
"vehicles": []
}
```
#### `` 3. `500 Internal Server Error` ``
``` json
{
"error": "Failed to fetch vehicles"
}
```
---
### `Status Codes Reference`
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Successfully retrieved vehicles list (can be an empty array). |
| **`500 Internal Server Error`** | Server or database query failure. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.