Vehicles API: Fleet Registration and Availability Search

The Vehicles API is the core of KaroKar’s fleet management layer. It lets privileged users register new vehicles under an organization, then exposes a real-time availability search that respects the full vehicle lifecycle. A vehicle moves through four statuses — PENDING, ACTIVE, SUSPENDED, and RETIRED — and can be owned by a vendor or a corporate client, expressed via the ownershipType field. The availability search engine is the most powerful endpoint: it cross-references vehicle status, active bookings, and maintenance windows to return only vehicles that are genuinely free for the requested date range. All three endpoints require a valid bearer token and the appropriate permission from the PermissionGuard.

POST /vehicles

Registers a new vehicle in the fleet under a given organization. Required permission: vehicle.create

Newly registered vehicles are placed in PENDING status and are not returned by the availability search until they have been activated. Use the vehicle activation flow (via the service layer) to transition a vehicle to ACTIVE.

Request body

organizationId

string (UUID)

required

The UUID of the organization that owns this vehicle. Must reference an existing organization.

ownershipType

VehicleOwnershipType

required

How the vehicle is owned. Must be one of the VehicleOwnershipType enum values.

Show VehicleOwnershipType values

Value	Description
`VENDOR_OWNED`	Vehicle is owned and operated by a fleet vendor.
`CORPORATE_OWNED`	Vehicle is owned by a corporate client and managed through the platform.

make

string

required

Manufacturer name of the vehicle (e.g., "Toyota", "Mahindra").

model

string

required

Model name of the vehicle (e.g., "Innova Crysta", "XUV700").

year

integer

required

Four-digit model year. Must be between 1900 and 2100 (inclusive), validated by @Min(1900) and @Max(2100).

licensePlate

string

required

The vehicle’s registration / license plate number as it appears on the registration certificate.

Response

Returns the newly created Vehicle object.

string

UUID primary key, auto-generated.

organizationId

string

UUID of the owning organization.

ownershipType

VehicleOwnershipType

VENDOR_OWNED or CORPORATE_OWNED.

make

string

Manufacturer name.

model

string

Model name.

year

integer

Four-digit model year.

licensePlate

string

Registration / license plate number.

status

VehicleStatus

Current lifecycle status of the vehicle.

Show VehicleStatus values

Value	Meaning
`PENDING`	Registered but not yet activated. Excluded from availability search.
`ACTIVE`	Fully operational and eligible to appear in availability search results.
`SUSPENDED`	Temporarily deactivated; excluded from availability search.
`RETIRED`	Permanently removed from service; excluded from availability search.

createdAt

string (ISO 8601)

Timestamp of record creation, set automatically by the database.

updatedAt

string (ISO 8601)

Timestamp of the last update, maintained automatically by the database.

Example

curl -X POST http://localhost:3000/vehicles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ownershipType": "VENDOR_OWNED",
    "make": "Toyota",
    "model": "Innova Crysta",
    "year": 2022,
    "licensePlate": "KA-01-MN-4567"
  }'

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "ownershipType": "VENDOR_OWNED",
  "make": "Toyota",
  "model": "Innova Crysta",
  "year": 2022,
  "licensePlate": "KA-01-MN-4567",
  "status": "PENDING",
  "createdAt": "2024-06-01T11:00:00.000Z",
  "updatedAt": "2024-06-01T11:00:00.000Z"
}

Error cases

Status	Reason
`401 Unauthorized`	Missing or expired `Authorization` bearer token.
`403 Forbidden`	Authenticated principal lacks the `vehicle.create` permission.
`400 Bad Request`	Validation failure — e.g., `year` is outside the 1900–2100 range, or `ownershipType` is not a valid enum value.

GET /vehicles/search

Returns all vehicles belonging to an organization that are genuinely available for booking within the specified date range. Required permission: vehicle.read

The availability engine filters out any vehicle whose status is not ACTIVE, and additionally excludes vehicles that have an overlapping booking, allocation, or maintenance window for the requested startDate–endDate range. Only vehicles that are free for the entire requested period are returned.

Query parameters

organizationId

string (UUID)

required

Scopes the search to the fleet owned by this organization.

startDate

string (ISO 8601 date)

required

The start of the desired availability window. Must be a valid ISO 8601 date string (e.g., 2024-07-01).

endDate

string (ISO 8601 date)

required

The end of the desired availability window. Must be a valid ISO 8601 date string (e.g., 2024-07-07). Must be after startDate.

Response

Returns an array of Vehicle objects that are available for the full requested date range. An empty array [] means no vehicles are available; it is not an error.

[]

Vehicle[]

Each element is a full Vehicle object with the same shape as the POST /vehicles response.

Show Vehicle fields

string

UUID primary key.

organizationId

string

UUID of the owning organization.

ownershipType

VehicleOwnershipType

VENDOR_OWNED or CORPORATE_OWNED.

make

string

Manufacturer name.

model

string

Model name.

year

integer

Four-digit model year.

licensePlate

string

Registration / license plate number.

status

VehicleStatus

Always ACTIVE for results returned by this endpoint.

createdAt

string (ISO 8601)

Record creation timestamp.

updatedAt

string (ISO 8601)

Last update timestamp.

Example

curl "http://localhost:3000/vehicles/search?organizationId=f47ac10b-58cc-4372-a567-0e02b2c3d479&startDate=2024-07-01&endDate=2024-07-07" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ownershipType": "VENDOR_OWNED",
    "make": "Toyota",
    "model": "Innova Crysta",
    "year": 2022,
    "licensePlate": "KA-01-MN-4567",
    "status": "ACTIVE",
    "createdAt": "2024-06-01T11:00:00.000Z",
    "updatedAt": "2024-06-01T11:00:00.000Z"
  }
]

Error cases

Status	Reason
`401 Unauthorized`	Missing or expired `Authorization` bearer token.
`403 Forbidden`	Authenticated principal lacks the `vehicle.read` permission.
`400 Bad Request`	Validation failure — e.g., `organizationId` is not a valid UUID, or `startDate` / `endDate` are not valid ISO 8601 date strings.

GET /vehicles/:id

Retrieves a single vehicle by its UUID. Required permission: vehicle.read

This endpoint returns null (with a 200 status) when no vehicle matches the given ID. Check the response body for null before reading vehicle fields in your client.

Path parameters

string

required

The UUID of the vehicle to retrieve.

Response

Returns the matching Vehicle object, or null if no record exists for the provided ID.

string

UUID primary key of the vehicle.

organizationId

string

UUID of the owning organization.

ownershipType

VehicleOwnershipType

VENDOR_OWNED or CORPORATE_OWNED.

make

string

Manufacturer name.

model

string

Model name.

year

integer

Four-digit model year.

licensePlate

string

Registration / license plate number.

status

VehicleStatus

Current lifecycle status: PENDING, ACTIVE, SUSPENDED, or RETIRED.

createdAt

string (ISO 8601)

Timestamp of record creation.

updatedAt

string (ISO 8601)

Timestamp of the last update.

Example

curl http://localhost:3000/vehicles/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Authorization: Bearer <token>"

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "organizationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "ownershipType": "VENDOR_OWNED",
  "make": "Toyota",
  "model": "Innova Crysta",
  "year": 2022,
  "licensePlate": "KA-01-MN-4567",
  "status": "ACTIVE",
  "createdAt": "2024-06-01T11:00:00.000Z",
  "updatedAt": "2024-06-01T11:00:00.000Z"
}

Error cases

Status	Reason
`401 Unauthorized`	Missing or expired `Authorization` bearer token.
`403 Forbidden`	Authenticated principal lacks the `vehicle.read` permission.

Overview

Identity

Fleet

Operations

Vehicles API: Fleet Registration and Availability Search

POST /vehicles

Request body

Response

Example

Error cases

GET /vehicles/search

Query parameters

Response

Example

Error cases

GET /vehicles/:id

Path parameters

Response

Example

Error cases

Build docs developers (and LLMs) love

Overview

Identity

Fleet

Operations

Documentation Index

​POST /vehicles

​Request body

​Response

​Example

​Error cases

​GET /vehicles/search

​Query parameters

​Response

​Example

​Error cases

​GET /vehicles/:id

​Path parameters

​Response

​Example

​Error cases

Build docs developers (and LLMs) love

POST /vehicles

Request body

Response

Example

Error cases

GET /vehicles/search

Query parameters

Response

Example

Error cases

GET /vehicles/:id

Path parameters

Response

Example

Error cases