Vehicles (v1)

Download OpenAPI specification:Download

Use the Vehicles API to manage vehicle fleet registry in ChargEye, with a particular focus on buses, trucks, and other commercial or work vehicles.

This API is structured into two segments:

  • "Vehicle Registry" for the detailed management of individual vehicles, and
  • "Scheduling" to organize and optimize the charging schedules at the depot.

Utilizing this API requires a ChargEye for Depots license.

Optimizing the charging process based on individual vehicle schedules is a feature of ChargEye Depot Master - decreasing charging costs, enhancing efficiency and energy management.

A vehicle within this API is identified not just by its unique ID but also by the MAC address of its charging controller. The MAC address is used to recognize it as the individual vehicle at charging stations. Attributes extend to user-defined names, model & make, license plate, and free-form notes. Each vehicle is associated with technical attributes such as the net battery size (fullChargeEnergykWh) and maximum charge power, which are needed for full functionality of ChargEye Depot Master.

Schedules represent the time slot when a vehicle is expected at the depot for charging. Each schedule is associated with a vehicle, and detail the expected arrival and departure times and the targeted State of Charge (SoC). The initial SoC upon arrival can be estimated and set by an external system based on the expected vehicle consumption and the daily trip. Schedules are date-specific but can also be set to recur for vehicles with regular operational routines.

Scheduling

Get Schedules for a Location

get/locations/{locationUid}/schedules

Obtains the charging schedules happening on the location specified with locationUid. See Locations API for description of a Location.

The schedules provide details like estimated arrival and departure times of vehicles.

SecuritybearerAuth
Request
path Parameters
locationUid
required
string
query Parameters
endTime
string

Time range end time in ISO 8601 format

limit
number

Limit the number of schedules returned

startTime
string

Time range start time in ISO 8601 format

Responses
200

OK

Response Schema: application/json
required
Array of objects (EvSchedule)
Array
evId
required
string

ID of the vehicle

id
required
string

GUID of this specific schedule

locationUid
string or null

Location uid for this schedule, format e.g. Lxxxxxx If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)

object (OptimizedSchedule)
object (OptimizedScheduleMeta)
plannedArrivalTime
string

Estimated time of arrival ISO timestamp

plannedDepartureTime
required
string

Time of departure ISO timestamp

recurrenceRule
string or null

Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule

startSoC
number >= 0

estimated start state of charge as a percentage

targetSoC
number >= 0

target state of charge as a percentage

required
Array of objects (EvSchedule)
Array
evId
required
string

ID of the vehicle

id
required
string

GUID of this specific schedule

locationUid
string or null

Location uid for this schedule, format e.g. Lxxxxxx If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)

object (OptimizedSchedule)
object (OptimizedScheduleMeta)
plannedArrivalTime
string

Estimated time of arrival ISO timestamp

plannedDepartureTime
required
string

Time of departure ISO timestamp

recurrenceRule
string or null

Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule

startSoC
number >= 0

estimated start state of charge as a percentage

targetSoC
number >= 0

target state of charge as a percentage

401

Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission

Request samples 
Response samples 
application/json
{
  • "recurringSchedules": [
    ],
  • "schedules": [
    ]
}
Get Schedules for a Vehicle
get/vehicles/{vehicleId}/schedules
This endpoint returns the charging schedules associated with a specific vehicle, identified by its vehicleId.
The response includes an array of schedules with details like estimated arrival and departure times at the depots.
Allows filtering results with query parameters by time range.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
query Parameters
endTime
string
Time range start time in ISO 8601 format


 
limit
number
Limit the number of schedules returned


 
startTime
string
Time range start time in ISO 8601 format


 
Responses 
200
OK


Response Schema: application/json
required
Array of objects (EvSchedule) 
 
 Array 
evId
required
string
ID of the vehicle


 
id
required
string
GUID of this specific schedule


 
locationUid
string or null
Location uid for this schedule, format e.g. Lxxxxxx
If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)


 
object (OptimizedSchedule) 
 
object (OptimizedScheduleMeta) 
 
plannedArrivalTime
string
Estimated time of arrival ISO timestamp


 
plannedDepartureTime
required
string
Time of departure ISO timestamp


 
recurrenceRule
string or null
Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule


 
startSoC
number  >= 0 
estimated start state of charge as a percentage


 
targetSoC
number  >= 0 
target state of charge as a percentage


 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "schedules": [
    ]
}
Create Schedules for a Vehicle
post/vehicles/{vehicleId}/schedules
Allows the addition of new charging schedules for a Vehicle,
specifying the timing and location for planned charging sessions.


May be used to update all schedules (that have not yet passed) with the replaceFutureSchedules flag.
This is the endpoint to use for most integration use cases.
You may call this endpoint with information on all upcoming schedules, and this API will take care of
updating, creating and deleting schedules based on the passed in schedules.


With the replaceFutureSchedules flag, new schedule entries specified in the request will be created.
If there is an upcoming schedule entry in ChargEye but not present in the request, it will be deleted.
Existing schedules entries will be identified by the departure time and updated if necessary.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
query Parameters
replaceFutureSchedules
boolean
Set this as true if you want to delete all future schedules for this vehicle and replace them with the ones provided in the request. Will also replace the current schedule if its departure time is in the future


 
Request Body schema: application/json
required
replaceFutureSchedules
boolean
Set this as true if you want to delete all future schedules for this vehicle and replace them
with the ones provided in the request. Will also replace the current schedule if
its departure time is in the future.


If you submit a schedule that has arrival time in the past and departure time in the future,
it will either update an existing ongoing schedule (or one that has very recently ended)
or create a new one (if no matching schedule is found).


 
required
Array of objects (PostedSchedule) 
 
 Array 
locationUid
string or null
Location uid for this schedule, format e.g. Lxxxxxx
If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)


 
object (OptimizedSchedule) 
 
object (OptimizedScheduleMeta) 
 
plannedArrivalTime
string
Estimated time of arrival ISO timestamp


 
plannedDepartureTime
required
string
Time of departure ISO timestamp


 
recurrenceRule
string or null
Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule


 
startSoC
number  >= 0 
estimated start state of charge as a percentage


 
targetSoC
number  >= 0 
target state of charge as a percentage


 
Responses 
200
OK


Response Schema: application/json
ids
required
Array of strings
 
removedScheduleIds
Array of strings
 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
application/json
{
  • "replaceFutureSchedules": true,
  • "schedules": [
    ]
}
Response samples 
application/json
{
  • "ids": [
    ],
  • "removedScheduleIds": [
    ]
}
Update Schedules of a Vehicle
patch/vehicles/{vehicleId}/schedules
Modifies specific details of a vehicle's existing charging schedules.
Suitable for adjustments to timing or location.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Request Body schema: application/json
required
required
Array of objects (EvSchedulePatch) 
 
 Array 
id
required
string
 
locationUid
string or null
Location uid for this schedule, format e.g. Lxxxxxx
If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)


 
object (OptimizedSchedule) 
 
object (OptimizedScheduleMeta) 
 
plannedArrivalTime
string
Estimated time of arrival ISO timestamp


 
plannedDepartureTime
string
Time of departure ISO timestamp


 
recurrenceRule
string or null
Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule


 
startSoC
number  >= 0 
estimated start state of charge as a percentage


 
targetSoC
number  >= 0 
target state of charge as a percentage


 
Responses 
200
OK


Response Schema: application/json
message
string
 
skippedScheduleIds
Array of strings
The patch response will be 200 in case any of the schedules succeed. In the case that some of the patches failed, the id's of the schedules are returned in skippedScheduleIds


 
success
required
boolean
 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
application/json
{
  • "schedules": [
    ]
}
Response samples 
application/json
{
  • "message": "string",
  • "skippedScheduleIds": [
    ],
  • "success": true
}
Delete Schedules of a Vehicle
delete/vehicles/{vehicleId}/schedules
Removes specific charging schedules, by their schedule ids, of a particular Vehicle.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Responses 
200
OK


Response Schema: application/json
success
required
boolean
 Value: true  
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "success": true
}
Get next Schedule for a Vehicle
get/vehicles/{vehicleId}/schedules/active
Retrieves the upcoming active schedule for a specified vehicle, identified by its vehicleId.
The response can include the last ended schedule and the current or next schedule to become active.
Each schedule provides detailed information like estimated arrival and departure times.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
query Parameters
endTime
string
Optional: For limiting the look up time range of the currentOrNext schedule, returns nothing if no schedules in the time range. Timestamp in ISO 8601 format


 
startTime
string
Optional: For limiting the look up time range of the previous schedule, returns nothing if no schedules in the time range. Timestamp in ISO 8601 format


 
Responses 
200
OK


Response Schema: application/json
object (EvSchedule) 
 
evId
required
string
ID of the vehicle


 
id
required
string
GUID of this specific schedule


 
locationUid
string or null
Location uid for this schedule, format e.g. Lxxxxxx
If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)


 
object (OptimizedSchedule) 
 
object (OptimizedScheduleMeta) 
 
plannedArrivalTime
string
Estimated time of arrival ISO timestamp


 
plannedDepartureTime
required
string
Time of departure ISO timestamp


 
recurrenceRule
string or null
Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule


 
startSoC
number  >= 0 
estimated start state of charge as a percentage


 
targetSoC
number  >= 0 
target state of charge as a percentage


 
object (EvSchedule) 
 
evId
required
string
ID of the vehicle


 
id
required
string
GUID of this specific schedule


 
locationUid
string or null
Location uid for this schedule, format e.g. Lxxxxxx
If missing, defaults to EV's location (if EV has multiple locations, behavior is ambiguous)


 
object (OptimizedSchedule) 
 
object (OptimizedScheduleMeta) 
 
plannedArrivalTime
string
Estimated time of arrival ISO timestamp


 
plannedDepartureTime
required
string
Time of departure ISO timestamp


 
recurrenceRule
string or null
Recurrence rule, iCalendar RFC, parse and generate with https://www.npmjs.com/package/rrule


 
startSoC
number  >= 0 
estimated start state of charge as a percentage


 
targetSoC
number  >= 0 
target state of charge as a percentage


 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "currentOrNext": {
    },
  • "previous": {
    }
}
Vehicle registry
List Vehicles
get/vehicles
Returns a list of vehicles and their associated data in the system.
Useful for obtaining an overview of all registered vehicles.


SecuritybearerAuth 
Request 
query Parameters
locationUid
string
Filter by locationUid


 
Responses 
200
OK


Response Schema: application/json
required
Array of objects (VehicleRecord) 
 
 Array 
object (V2icpInfo) 
 
required
object (VehicleDTO) 
 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "vehicles": [
    ]
}
Get a Vehicle
get/vehicles/{vehicleId}
Returns data for a specified vehicle ID, including attributes like name, model, and technical specifications.
The vehicleId can be obtained from the GET /vehicles endpoint.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Responses 
200
OK


Response Schema: application/json
Array of objects (ChargingPort) 
Charging ports for this EV


 
 Array 
inactive
boolean
 
macAddress
required
string
 
type
string
 Enum: "CCS2" "ChaDeMo" "MCS" "NACS"  
consumption
number
EV consumption Wh/km - used to calculate the added range


 
enableChargeScheduling
boolean
If true, this EV's charging is controlled by the departure schedule set in ChargEye.


 
evMacAddress
string or null
 Deprecated 
MAC address of vehicle. Deprecated field. Use chargingPorts instead. Some EVs have multiple charging ports, and each can have its own MAC address. This field is kept for backwards compatibility.


 
evModel
string
model&make of the vehicle


 
fullChargeEnergykWh
number  >= 1 
Estimate of energy required to charge from 0 to 100% (estimate of battery size)


 
id
required
string
 
licensePlate
string
license/registry plate


 
(Array of strings or null) or (string or null)
 
Any of:
 Array 
string
 
maxChargePowerkW
number  >= 1 
Maximum power this EV is capable of charging at, indicative


 
minChargePowerkW
number  >= 0 
Minimum power this EV is capable of charging at


 
minPreconditioningPowerkW
number
Minimum power EV is allowed to do preconditioning


 
name
string
user given name for the vehicle


 
notes
string
additional notes or description


 
supportsPauseResume
boolean
Set to true if this EV is capable of pausing and resuming, e.g. some buses


 
object (V2icpInfo) 
 
evMacAddress
string
EV mac address


 
locationUid
string
Last known location of EV


 
odometer
number
Number of kilometers this vehicle has traveled in total


 
passwordId
string
The passwordId used in this v2icp session


 
response
any
    

  • ChargEye-sent response to the bus
    • 



 
timestamp
required
string
Timestamp of the V2ICP message


 
v2icp
required
any
Original raw message from vehicle


 
vin
required
string
VIN number


 
object (V2icpParameters) 
 
ambientTemp
number or null
If wish to override ambient temperature for testing purposes


 
interiorHvac
string
Interior HVAC preconditioning - HVAC = Heating, Ventilation, Air Conditioning


 Enum: "HotWaterAndHeating" "NoHotWaterCoolingOrVentilation" "NoPreconditioning" "OnlyHotWaterAndVentilation"  
preconditioning
boolean
General preconditioning - DMS = Depot Management System


 
vin
string
Vehicle identification number *


 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "chargingPorts": [
    ],
  • "consumption": 0,
  • "enableChargeScheduling": true,
  • "evMacAddress": "string",
  • "evModel": "string",
  • "fullChargeEnergykWh": 1,
  • "id": "string",
  • "licensePlate": "string",
  • "locationUid": [
    ],
  • "maxChargePowerkW": 1,
  • "minChargePowerkW": 0,
  • "minPreconditioningPowerkW": 0,
  • "name": "string",
  • "notes": "string",
  • "supportsPauseResume": true,
  • "v2icp": {
    },
  • "v2icpParameters": {
    },
  • "vin": "string"
}
Create a Vehicle
put/vehicles/{vehicleId}
Adds a new vehicle or updates an existing one based on the vehicleId path parameter.
You may choose the vehicleId yourself for new entries.


While vehicles are identified by their id in the vehicle registry,
the evMacAddress field is important for identifying it at the charging station.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Request Body schema: application/json
required
Array of objects (ChargingPort) 
Charging ports for this EV


 
 Array 
inactive
boolean
 
macAddress
required
string
 
type
string
 Enum: "CCS2" "ChaDeMo" "MCS" "NACS"  
consumption
number
EV consumption Wh/km - used to calculate the added range


 
enableChargeScheduling
boolean
If true, this EV's charging is controlled by the departure schedule set in ChargEye.


 
evMacAddress
string or null
 Deprecated 
MAC address of vehicle. Deprecated field. Use chargingPorts instead. Some EVs have multiple charging ports, and each can have its own MAC address. This field is kept for backwards compatibility.


 
evModel
string
model&make of the vehicle


 
fullChargeEnergykWh
number  >= 1 
Estimate of energy required to charge from 0 to 100% (estimate of battery size)


 
licensePlate
string
license/registry plate


 
(Array of strings or null) or (string or null)
 
Any of:
 Array 
string
 
maxChargePowerkW
number  >= 1 
Maximum power this EV is capable of charging at, indicative


 
minChargePowerkW
number  >= 0 
Minimum power this EV is capable of charging at


 
minPreconditioningPowerkW
number
Minimum power EV is allowed to do preconditioning


 
name
string
user given name for the vehicle


 
notes
string
additional notes or description


 
supportsPauseResume
boolean
Set to true if this EV is capable of pausing and resuming, e.g. some buses


 
object (V2icpParameters) 
 
ambientTemp
number or null
If wish to override ambient temperature for testing purposes


 
interiorHvac
string
Interior HVAC preconditioning - HVAC = Heating, Ventilation, Air Conditioning


 Enum: "HotWaterAndHeating" "NoHotWaterCoolingOrVentilation" "NoPreconditioning" "OnlyHotWaterAndVentilation"  
preconditioning
boolean
General preconditioning - DMS = Depot Management System


 
Responses 
200
OK


Response Schema: application/json
id
required
string
 
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
application/json
{
  • "chargingPorts": [
    ],
  • "consumption": 0,
  • "enableChargeScheduling": true,
  • "evMacAddress": "string",
  • "evModel": "string",
  • "fullChargeEnergykWh": 1,
  • "licensePlate": "string",
  • "locationUid": [
    ],
  • "maxChargePowerkW": 1,
  • "minChargePowerkW": 0,
  • "minPreconditioningPowerkW": 0,
  • "name": "string",
  • "notes": "string",
  • "supportsPauseResume": true,
  • "v2icpParameters": {
    }
}
Response samples 
application/json
{
  • "id": "string"
}
Update a Vehicle
patch/vehicles/{vehicleId}
Partially updates the attributes of a specified vehicle.
Ideal for modifying specific data fields without replacing the entire vehicle entry.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Request Body schema: application/json
required
Array of objects (ChargingPort) 
Charging ports for this EV


 
 Array 
inactive
boolean
 
macAddress
required
string
 
type
string
 Enum: "CCS2" "ChaDeMo" "MCS" "NACS"  
consumption
number
EV consumption Wh/km - used to calculate the added range


 
enableChargeScheduling
boolean
If true, this EV's charging is controlled by the departure schedule set in ChargEye.


 
evMacAddress
string or null
 Deprecated 
MAC address of vehicle. Deprecated field. Use chargingPorts instead. Some EVs have multiple charging ports, and each can have its own MAC address. This field is kept for backwards compatibility.


 
evModel
string
model&make of the vehicle


 
fullChargeEnergykWh
number  >= 1 
Estimate of energy required to charge from 0 to 100% (estimate of battery size)


 
licensePlate
string
license/registry plate


 
(Array of strings or null) or (string or null)
 
Any of:
 Array 
string
 
maxChargePowerkW
number  >= 1 
Maximum power this EV is capable of charging at, indicative


 
minChargePowerkW
number  >= 0 
Minimum power this EV is capable of charging at


 
minPreconditioningPowerkW
number
Minimum power EV is allowed to do preconditioning


 
name
string
user given name for the vehicle


 
notes
string
additional notes or description


 
supportsPauseResume
boolean
Set to true if this EV is capable of pausing and resuming, e.g. some buses


 
object (V2icpParameters) 
 
ambientTemp
number or null
If wish to override ambient temperature for testing purposes


 
interiorHvac
string
Interior HVAC preconditioning - HVAC = Heating, Ventilation, Air Conditioning


 Enum: "HotWaterAndHeating" "NoHotWaterCoolingOrVentilation" "NoPreconditioning" "OnlyHotWaterAndVentilation"  
preconditioning
boolean
General preconditioning - DMS = Depot Management System


 
Responses 
200
OK


Response Schema: application/json
success
required
boolean
 Value: true  
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
application/json
{
  • "chargingPorts": [
    ],
  • "consumption": 0,
  • "enableChargeScheduling": true,
  • "evMacAddress": "string",
  • "evModel": "string",
  • "fullChargeEnergykWh": 1,
  • "licensePlate": "string",
  • "locationUid": [
    ],
  • "maxChargePowerkW": 1,
  • "minChargePowerkW": 0,
  • "minPreconditioningPowerkW": 0,
  • "name": "string",
  • "notes": "string",
  • "supportsPauseResume": true,
  • "v2icpParameters": {
    }
}
Response samples 
application/json
{
  • "success": true
}
Delete a Vehicle
delete/vehicles/{vehicleId}
Removes a specified vehicle from the registry.
Removing a vehicle will not remove any associated data such as charging sessions.


SecuritybearerAuth 
Request 
path Parameters
vehicleId
required
string
 
Responses 
200
OK


Response Schema: application/json
success
required
boolean
 Value: true  
401
Unauthorized - Authorization: Bearer header is missing, invalid, expired, or user has no permission


Request samples 
Response samples 
application/json
{
  • "success": true
}