Vehicle Configuration API

Black Swan Automotive Connected Vehicles · Svanholm digital twin · v1.4.2 · back to the twin · OpenAPI

The twin runs a copy of the production driving computer for every car in the fleet. This API is the same configuration service the dealer tools use, pointed at the twin instead of at the road. Anything the service can change on a real car it can change here, and the car in the twin will drive with it.

Authentication is by vehicle identification number. Send it on every vehicle call as Authorization: VIN <vin> (X-VIN works too). The VIN is on the car.

Worlds

Each visitor gets a world: one city, one fleet, its own VINs. Share the world URL with your team and you all look at the same cars. Worlds nobody watches or calls for thirty minutes are dropped.

POST/api/v1/worlds

Create a world. Returns its id, the viewer URL, the stream URL and the fleet with every VIN.

curl -X POST https://twin.chal.blackswantrainingcenter.com/api/v1/worlds

GET/api/v1/worlds/{id}

The fleet of a world: model, plate, colour and VIN of every car, plus the hazard spots in the city.

GET/api/v1/worlds/{id}/map

The road network: roads, junctions, lanes as polylines, blocks, hazard locations. Metres, x east, y north.

GET/api/v1/worlds/{id}/state

One snapshot of every car, light and hazard. The WebSocket at /ws/worlds/{id} streams the same message at 12.5 Hz, preceded by a hello with the fleet.

GET/api/v1/worlds/{id}/incidents

Every collision report in the world, in order, including which systems failed and what that earned.

GET/api/v1/worlds/{id}/events

The last sixty events: hazards, interventions, configuration changes, collisions.

Features

GET/api/v1/features

The catalogue. Three groups. Functions are what an owner can switch in the car's menu. Sensors and actuators are engineering items: they never appear in the owner menu, but this service does not distinguish.

Name	Group	Needs
`steering`	actuator
`brakes`	actuator
`throttle`	actuator
`front_camera`	sensor
`front_radar`	sensor
`corner_radars`	sensor
`aeb`	function	brakes, and front_radar or front_camera
`animal_detection`	function	front_camera
`evasive_steering`	function	steering, front_camera
`traffic_light_recognition`	function	front_camera, brakes
`intersection_assist`	function	corner_radars, brakes
`esc`	function	brakes, steering

A function that is switched on but misses something it needs is reported as degraded in the effective map. The car drives with what is effective, not with what is switched on.

Vehicle

All vehicle calls take the VIN header and act on that car.

GET/api/v1/vehicle

Identity, configuration, effective configuration, live telemetry and the incident ids of this car.

curl https://twin.chal.blackswantrainingcenter.com/api/v1/vehicle -H 'Authorization: VIN BSWN-KRP-2025-12345'

GET/api/v1/vehicle/features

Declared and effective features only.

PATCH/api/v1/vehicle/features

Change any number of features at once. Body is a JSON object of feature name to boolean.

curl -X PATCH https://twin.chal.blackswantrainingcenter.com/api/v1/vehicle/features \
  -H 'Authorization: VIN BSWN-KRP-2025-12345' \
  -H 'Content-Type: application/json' \
  -d '{"aeb": false, "front_camera": false}'

PUT/api/v1/vehicle/features/{name}

Set one feature. Body: {"enabled": false}.

POST/api/v1/vehicle/features/reset

Everything back on.

GET/api/v1/vehicle/telemetry

Position, heading, speed, road, gap to the vehicle ahead, whether AEB or ESC is intervening right now.

GET/api/v1/vehicle/route

The loop this car drives, as lane ids and as a list of streets. Useful to know which hazards it will meet.

GET/api/v1/vehicle/incidents

Collision reports involving this car. A report lists every vehicle, the systems that were off, the failures that explain the collision, and whatever that earned.

Errors

Errors are JSON with an error and usually a hint. 401 without a VIN or with an unknown one, 404 for an unknown world, 400 for an unknown feature or a value that is not a boolean.