{"openapi":"3.1.0","info":{"title":"Aerovolt Charge Network API","version":"1.2.0","description":"Server-to-server API for monitoring and controlling Aerovolt OCPP charge points. All /api/v1 endpoints in this document require the fixed bearer API key."},"servers":[{"url":"https://ocpp.aerovolt.co.uk/api/v1","description":"Aerovolt production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Charge points"},{"name":"Network structure"},{"name":"Sessions"},{"name":"Commands"},{"name":"ID tags"},{"name":"AutoCharge"},{"name":"Events"}],"paths":{"/chargers":{"get":{"tags":["Charge points"],"operationId":"listChargePoints","summary":"List charge points","responses":{"200":{"description":"Charge points","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargePoint"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/chargers/{id}":{"get":{"tags":["Charge points"],"operationId":"getChargePoint","summary":"Get charge point and connector state","parameters":[{"$ref":"#/components/parameters/ChargePointId"}],"responses":{"200":{"description":"Charge point detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChargePoint"},"connectors":{"type":"array","items":{"$ref":"#/components/schemas/Connector"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/pricing":{"get":{"tags":["Charge points"],"operationId":"listNetworkPricing","summary":"Get current network energy pricing","responses":{"200":{"description":"Live configured charger prices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Pricing"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/chargers/{id}/pricing":{"get":{"tags":["Charge points"],"operationId":"getChargePointPricing","summary":"Get current charge point energy pricing","parameters":[{"$ref":"#/components/parameters/ChargePointId"}],"responses":{"200":{"description":"Live configured price","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Pricing"}},"required":["data"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/soc":{"get":{"tags":["Charge points"],"operationId":"listNetworkSoc","summary":"Get latest vehicle state of charge across the network","responses":{"200":{"description":"Latest charger-reported SoC values","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Soc"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/chargers/{id}/soc":{"get":{"tags":["Charge points"],"operationId":"getChargePointSoc","summary":"Get latest vehicle state of charge for a charger","parameters":[{"$ref":"#/components/parameters/ChargePointId"}],"responses":{"200":{"description":"Latest connector SoC values","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Soc"}}},"required":["data"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/transactions":{"get":{"tags":["Sessions"],"operationId":"listTransactions","summary":"List charging sessions","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","COMPLETED"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Sessions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}},"required":["data"]}}}}}}},"/transactions/{id}":{"get":{"tags":["Sessions"],"operationId":"getTransactionDetail","summary":"Get complete live or historical session telemetry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Session, pricing snapshot, meter values and event timeline","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Transaction"},"meterValues":{"type":"array","items":{"$ref":"#/components/schemas/MeterValue"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/OcppEvent"}}},"required":["data","meterValues","events"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/chargers/{id}/events":{"get":{"tags":["Events"],"operationId":"listChargePointEvents","summary":"Recent raw OCPP events","parameters":[{"$ref":"#/components/parameters/ChargePointId"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"OCPP events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OcppEvent"}}},"required":["data"]}}}}}}},"/chargers/{id}/commands/external":{"post":{"tags":["Commands"],"operationId":"sendChargePointCommand","summary":"Send an OCPP 1.6 command","description":"The charge point must be online. For RemoteStopTransaction, use ocpp_transaction_id from an ACTIVE transaction.","parameters":[{"$ref":"#/components/parameters/ChargePointId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandRequest"},"examples":{"remoteStart":{"value":{"action":"RemoteStartTransaction","payload":{"connectorId":1,"idTag":"AERO-001"}}},"remoteStop":{"value":{"action":"RemoteStopTransaction","payload":{"transactionId":123}}},"reset":{"value":{"action":"Reset","payload":{"type":"Soft"}}}}}}},"responses":{"200":{"description":"Charger response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandResponse"}}}},"409":{"description":"Charge point offline","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"504":{"description":"Command timeout/rejection error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/external/id-tags":{"get":{"tags":["ID tags"],"operationId":"listIdTags","summary":"List authorization ID tags","responses":{"200":{"description":"ID tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IdTag"}}},"required":["data"]}}}}}}},"/external/id-tags/{idTag}":{"put":{"tags":["ID tags"],"operationId":"upsertIdTag","summary":"Create or update an ID tag","parameters":[{"$ref":"#/components/parameters/IdTag"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Accepted","Blocked","Expired","Invalid","ConcurrentTx"],"default":"Accepted"},"parentIdTag":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Saved ID tag","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IdTag"}},"required":["data"]}}}}}},"delete":{"tags":["ID tags"],"operationId":"deleteIdTag","summary":"Delete a local ID tag","parameters":[{"$ref":"#/components/parameters/IdTag"}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/external/autocharge/vehicles":{"get":{"tags":["AutoCharge"],"operationId":"listAutoChargeVehicles","summary":"List vehicles linked to an account ID tag","description":"Returns learned and API-created vehicle identities, including whether the user has granted AutoCharge consent.","parameters":[{"name":"idTag","in":"query","required":true,"schema":{"type":"string","maxLength":64},"example":"AERO-001"}],"responses":{"200":{"description":"Linked vehicles and consent state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutoChargeVehicle"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/external/autocharge/vehicles/{vehicleId}":{"get":{"tags":["AutoCharge"],"operationId":"getAutoChargeVehicle","summary":"Get one AutoCharge vehicle","parameters":[{"$ref":"#/components/parameters/VehicleId"}],"responses":{"200":{"description":"Vehicle and consent state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutoChargeVehicle"}},"required":["data"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["AutoCharge"],"operationId":"upsertAutoChargeVehicle","summary":"Add a vehicle or grant/revoke AutoCharge consent","description":"The ID tag must already exist. A vehicle identity is globally unique and cannot be linked to a second ID tag. Set autochargeEnabled=false to retain the vehicle association while revoking consent.","parameters":[{"$ref":"#/components/parameters/VehicleId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoChargeVehicleUpsert"},"example":{"idTag":"AERO-001","autochargeEnabled":true,"label":"Primary vehicle"}}}},"responses":{"200":{"description":"Saved vehicle and consent state","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutoChargeVehicle"}},"required":["data"]}}}},"404":{"description":"ID tag not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Vehicle is already linked to another ID tag","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"delete":{"tags":["AutoCharge"],"operationId":"archiveAutoChargeVehicle","summary":"Archive a vehicle association","parameters":[{"$ref":"#/components/parameters/VehicleId"},{"name":"idTag","in":"query","required":true,"schema":{"type":"string","maxLength":64},"example":"AERO-001"}],"responses":{"204":{"description":"Vehicle association archived; a fresh charger observation can offer it for assignment again"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/external/locations":{"get":{"tags":["Network structure"],"operationId":"listLocations","summary":"List OCPI locations and assigned charger counts","responses":{"200":{"description":"Locations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/external/groups":{"get":{"tags":["Network structure"],"operationId":"listChargePointGroups","summary":"List charge point groups and charger counts","responses":{"200":{"description":"Groups","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargePointGroup"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Fixed API_KEY configured on the Aerovolt server."}},"parameters":{"ChargePointId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"AV001"},"IdTag":{"name":"idTag","in":"path","required":true,"schema":{"type":"string","maxLength":64},"example":"AERO-001"},"VehicleId":{"name":"vehicleId","in":"path","required":true,"description":"Stable charger-reported vehicle identity (for example EVCCID/MAC). URL-encode separators when present.","schema":{"type":"string","maxLength":255},"example":"AABBCCDDEEFF"}},"responses":{"Unauthorized":{"description":"Missing or invalid bearer API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"schemas":{"ChargePoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string"},"ocpp_version":{"type":["string","null"]},"vendor":{"type":["string","null"]},"model":{"type":["string","null"]},"serial_number":{"type":["string","null"]},"firmware_version":{"type":["string","null"]},"max_power_w":{"type":["integer","null"],"description":"Configured whole-charge-point power ceiling in watts."},"connector_types":{"type":"array","description":"Compact connector/plug inventory for list responses.","items":{"type":"object","properties":{"connector_id":{"type":"integer"},"standard":{"type":"string"},"format":{"type":"string"},"power_type":{"type":"string"}},"required":["connector_id","standard","format","power_type"]}},"soc_percent":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Latest charger-reported vehicle state of charge."},"soc_updated_at":{"type":["string","null"],"format":"date-time"},"price_per_kwh":{"type":["number","null"],"description":"Current energy price per kWh."},"currency":{"type":"string","enum":["GBP","USD","EUR"]},"pricing":{"oneOf":[{"$ref":"#/components/schemas/PricingDetails"},{"type":"null"}],"description":"Structured current pricing; null when no price is configured."},"group_name":{"type":["string","null"]},"location_id":{"type":["string","null"]},"location_name":{"type":["string","null"]},"last_seen":{"type":["string","null"],"format":"date-time"}},"required":["id","status","currency"]},"Pricing":{"type":"object","properties":{"charge_point_id":{"type":"string"},"name":{"type":["string","null"]},"price_per_kwh":{"type":["number","null"]},"currency":{"type":"string","enum":["GBP","USD","EUR"]},"energy_unit":{"type":"string","const":"kWh"},"updated_at":{"type":"string","format":"date-time"}},"required":["charge_point_id","currency","energy_unit","updated_at"]},"PricingDetails":{"type":"object","properties":{"price_per_kwh":{"type":"number"},"currency":{"type":"string","enum":["GBP","USD","EUR"]},"energy_unit":{"type":"string","const":"kWh"},"updated_at":{"type":"string","format":"date-time"}},"required":["price_per_kwh","currency","energy_unit","updated_at"]},"Connector":{"type":"object","properties":{"charge_point_id":{"type":"string"},"connector_id":{"type":"integer"},"name":{"type":["string","null"]},"status":{"type":"string"},"error_code":{"type":["string","null"]},"standard":{"type":"string","description":"Canonical OCPI connector standard/plug type, for example IEC_62196_T2, GBT_AC or GBT_DC."},"format":{"type":"string","enum":["SOCKET","CABLE"]},"power_type":{"type":"string","enum":["AC_1_PHASE","AC_2_PHASE","AC_2_PHASE_SPLIT","AC_3_PHASE","DC"]},"max_voltage":{"type":"integer"},"max_amperage":{"type":"integer"},"max_power_w":{"type":["integer","null"],"description":"Configured connector power ceiling in watts."},"meter_wh":{"type":["integer","null"]},"soc_percent":{"type":["number","null"],"minimum":0,"maximum":100},"soc_updated_at":{"type":["string","null"],"format":"date-time"},"last_seen":{"type":["string","null"],"format":"date-time"}},"required":["charge_point_id","connector_id","status","standard","format","power_type","max_voltage","max_amperage"]},"Soc":{"type":"object","properties":{"charge_point_id":{"type":"string"},"name":{"type":["string","null"]},"connector_id":{"type":"integer"},"soc_percent":{"type":"number","minimum":0,"maximum":100},"soc_updated_at":{"type":"string","format":"date-time"}},"required":["charge_point_id","connector_id","soc_percent","soc_updated_at"]},"ChargePointGroup":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"charger_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","charger_count"]},"Location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"latitude":{"type":"string"},"longitude":{"type":"string"},"timezone":{"type":"string"},"published":{"type":"boolean"},"charger_count":{"type":"integer"},"charge_points":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string"},"soc_percent":{"type":["number","null"],"minimum":0,"maximum":100},"soc_updated_at":{"type":["string","null"],"format":"date-time"},"pricing":{"oneOf":[{"$ref":"#/components/schemas/PricingDetails"},{"type":"null"}]}},"required":["id","status"]}},"last_updated":{"type":"string","format":"date-time"}},"required":["id","name","address","city","postal_code","country","latitude","longitude","published","charger_count","charge_points"]},"Transaction":{"type":"object","properties":{"id":{"type":"integer"},"ocpp_transaction_id":{"type":["integer","null"]},"charge_point_id":{"type":"string"},"charge_point_name":{"type":["string","null"]},"connector_id":{"type":"integer"},"connector_name":{"type":["string","null"]},"connector_standard":{"type":["string","null"]},"connector_format":{"type":["string","null"],"enum":["SOCKET","CABLE",null]},"connector_power_type":{"type":["string","null"]},"id_tag":{"type":["string","null"],"description":"Underlying OCPP authorization token. User interfaces display the OCPI provider name for roaming sessions."},"ocpi_provider_name":{"type":["string","null"],"description":"Human-readable OCPI connection that initiated the session."},"vehicle_id":{"type":["string","null"]},"vehicle_id_source":{"type":["string","null"]},"autocharge_enabled":{"type":["boolean","null"],"description":"Current consent state for the linked vehicle; null when no vehicle is linked."},"autocharge_consented_at":{"type":["string","null"],"format":"date-time"},"soc_percent":{"type":["number","null"],"minimum":0,"maximum":100},"soc_updated_at":{"type":["string","null"],"format":"date-time"},"price_per_kwh":{"type":["number","null"]},"currency":{"type":["string","null"],"enum":["GBP","USD","EUR",null]},"estimated_cost":{"type":["number","null"]},"duration_seconds":{"type":"integer"},"energy_wh":{"type":"number"},"meter_start_wh":{"type":"integer"},"meter_stop_wh":{"type":["integer","null"]},"last_meter_wh":{"type":["integer","null"]},"started_at":{"type":"string","format":"date-time"},"stopped_at":{"type":["string","null"],"format":"date-time"},"stop_reason":{"type":["string","null"]},"status":{"type":"string","enum":["ACTIVE","COMPLETED"]}},"required":["id","charge_point_id","connector_id","started_at","status"]},"MeterValue":{"type":"object","properties":{"sampled_at":{"type":"string","format":"date-time"},"measurand":{"type":"string"},"value":{"type":"number"},"unit":{"type":["string","null"]},"context":{"type":["string","null"]},"phase":{"type":["string","null"]}},"required":["sampled_at","measurand","value"]},"IdTag":{"type":"object","properties":{"id_tag":{"type":"string"},"status":{"type":"string"},"parent_id_tag":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time"},"source":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id_tag","status"]},"AutoChargeVehicle":{"type":"object","properties":{"vehicle_id":{"type":"string","description":"Normalized stable identity supplied by the charger."},"id_tag":{"type":"string","description":"The single owning account ID tag."},"label":{"type":["string","null"]},"autocharge_enabled":{"type":"boolean"},"billing_exempt":{"type":"boolean","description":"When true, new sessions for this vehicle are priced at zero."},"price_override_per_kwh":{"type":["number","null"],"description":"Vehicle-specific energy price used instead of the charger tariff."},"price_override_currency":{"type":["string","null"],"enum":["GBP","USD","EUR",null]},"consent_status":{"type":"string","enum":["GRANTED","NOT_GRANTED"]},"consented_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"source":{"type":"string"},"first_seen":{"type":"string","format":"date-time"},"last_seen":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["vehicle_id","id_tag","autocharge_enabled","billing_exempt","consent_status","source","first_seen","last_seen","created_at","updated_at"]},"AutoChargeVehicleUpsert":{"type":"object","properties":{"idTag":{"type":"string","maxLength":64},"autochargeEnabled":{"type":"boolean","description":"Explicit Squadron user consent."},"label":{"type":["string","null"],"maxLength":120},"billingExempt":{"type":"boolean"},"priceOverridePerKwh":{"type":["number","null"],"minimum":0},"priceOverrideCurrency":{"type":["string","null"],"enum":["GBP","USD","EUR",null]}},"required":["idTag","autochargeEnabled"]},"OcppEvent":{"type":"object","properties":{"direction":{"type":"string","enum":["in","out"]},"message_type":{"type":"integer"},"unique_id":{"type":["string","null"]},"action":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"CommandRequest":{"type":"object","properties":{"action":{"type":"string","enum":["RemoteStartTransaction","RemoteStopTransaction","Reset","UnlockConnector","ChangeAvailability","ChangeConfiguration","GetConfiguration","ClearCache","TriggerMessage","UpdateFirmware","GetDiagnostics","SendLocalList","GetLocalListVersion","ReserveNow","CancelReservation","SetChargingProfile","ClearChargingProfile"]},"payload":{"type":"object","additionalProperties":true}},"required":["action","payload"]},"CommandResponse":{"type":"object","properties":{"result":{"type":"object","additionalProperties":true}},"required":["result"]}}}}