Admin vehicles

Browse the fleet and change a vehicle's operational status. Paths are relative to the /api/v1 prefix; these are back-office endpoints requiring an admin token.

Requires an admin bearer token (see Admin auth). Admin only.

See Common errors.

Endpoints

Method	URI	Access	Description
`GET`	`/admin/vehicles`	Admin	Paginated vehicle list with filters
`PATCH`	`/admin/vehicles/{vehicleId}/status`	Admin	Change a vehicle's status

GET /admin/vehicles

Page-paginated vehicle list (newest first), each with its driver summary. See Pagination → page-based.

Query

Field	Type	Required	Rules
`driver_status`	string	no	`PENDING_VERIFICATION`, `ACTIVE`, `SUSPENDED`, or `BANNED`
`min_capacity`	integer	no	≥ 0; min tank capacity (liters)
`max_capacity`	integer	no	≥ 0; max tank capacity (liters)
`has_motopump`	boolean	no	—
`cert_status`	string	no	`valid`, `expiring` (≤ 30 days), or `expired`
`q`	string	no	≤ 100 chars; matches plate, brand, model, or driver name
`limit`	integer	no	1–100, default `25`
`page`	integer	no	≥ 1, default `1`

Response 200

{
  "items": [
    {
      "id": 4,
      "plate": "ABC-123",
      "brand": "Ford",
      "model": "Cargo",
      "year": 2018,
      "capacity_liters": 5000,
      "hose_length_meters": 20,
      "has_motopump": true,
      "operation_radius_km": 15,
      "sanitary_cert_url": "https://…",
      "cert_expires_at": "2027-01-01T00:00:00+00:00",
      "cert_status": "valid",
      "driver": {
        "id": 3,
        "name": "Carlos Rodríguez",
        "phone": "+584241001001",
        "status": "ACTIVE",
        "is_online": true,
        "avg_rating": 4.8,
        "is_certified": true
      }
    }
  ],
  "meta": { "total": 20, "per_page": 25, "current_page": 1, "last_page": 1 }
}

cert_status is null when the vehicle has no cert_expires_at.

PATCH /admin/vehicles/{vehicleId}/status

Changes the vehicle's status. Valid transitions: ACTIVE ↔ MAINTENANCE ↔ OUT_OF_SERVICE (any of the three to either of the other two; no no-op).

Request body

Field	Type	Required	Rules
`status`	string	yes	`ACTIVE`, `MAINTENANCE`, or `OUT_OF_SERVICE`
`reason`	string	conditional	10–500 chars; required unless `status=ACTIVE`

Response 200

{
  "vehicle": {
    "id": 4,
    "plate": "ABC-123",
    "status": "MAINTENANCE",
    "driver": { "id": 3, "name": "Carlos Rodríguez" }
  },
  "audit_entry": {
    "from_status": "ACTIVE",
    "to_status": "MAINTENANCE",
    "reason": "Tanque en reparación",
    "admin_id": 1,
    "created_at": "2026-06-29T12:00:00+00:00"
  }
}

Errors

Status	Body	When
`404`	`{ "error": "VehicleNotFound" }`	No vehicle with that id
`422`	`{ "error": "InvalidTransition", "message": "…" }`	Not an allowed status change