Build on the
Black Swan platform.
One unified API for vehicles, customers, ownership and connected-mobility controls. Integrate your dealership tools, fleet analytics, or partner apps in minutes.
Vehicles
Query the full catalog, inspect any VIN, manage state (lock, climate, charging).
GET /api/cars
GET /api/state
PATCH /api/cars/{vin}/state
Customers
List, search and inspect your customer base. Supports self sign-up flows.
GET /api/customers
GET /api/customers/{username}
POST /api/auth/signup
Dealerships
Manage the dealer network: register, look up and administer dealerships.
GET /api/dealers
POST /api/dealers
DELETE /api/dealers/{username}
Ownership & Fleet
Assign owners, transfer vehicles between fleets, reset ownership.
PATCH /api/cars/{vin}/owner
DELETE /api/cars/{vin}/owner
POST /api/cars/add-to-fleet
Quick start
Authenticate and list dealerships in three calls:
# 1. Authenticate curl -X POST https://dealer.chal.blackswantrainingcenter.com/api/auth/login \ -H "Content-Type: application/json" \ -d '{"role":"user","username":"linnea","password":"linnea"}' # 2. Capture the token, then call any authenticated endpoint export TOKEN=<token from step 1> curl https://dealer.chal.blackswantrainingcenter.com/api/dealers \ -H "Authorization: Bearer $TOKEN" # 3. List every vehicle on the platform curl https://dealer.chal.blackswantrainingcenter.com/api/cars \ -H "Authorization: Bearer $TOKEN"
Tip: all endpoints are interactive at /docs. Click Authorize and paste your Bearer token to try them live.
Issue tracker
Reported defects and their status. Expand an entry to read it.
BSW-1874 · Pagination cap
per_page above 100 on list endpoints is clamped to 100; paging past the end returns an empty data array rather than 404.
BSW-1902 · Timestamps serialised in UTC
created_at / updated_at carry no offset; clients assuming local time render events a couple of hours off.
BSW-1931 · VIN lookup case-sensitive
GET /api/cars/{vin} matches the VIN exactly; a lower-cased VIN 404s though the record exists.
BSW-2003 · Service history ordering
Service records returned oldest-first; the reference implied newest-first.
BSW-2048 · Empty profile PATCH returns 200
PATCH /api/me/profile with no recognised field returns 200 and no-ops instead of 400.
BSW-2110 · Brief /api/state staleness
A reading up to ~2 s old may be served right after a mutation while the cache settles.
BSW-2137 · Coordinate precision
location.lat/lng rounded to four decimals (~11 m); not suitable for lane-level use.
BSW-2165 · Charging schedule timezone
A vehicle's charge schedule is evaluated in the car's registered region, not the account holder's.
BSW-2199 · Webhook duplicate delivery
On a delivery timeout the webhook retries with no idempotency guard; handlers must de-duplicate on event id.
BSW-2234 · Deprecated /api/v1 alias
/api/v1/* forwards to the current API for legacy clients; scheduled for removal.
BSW-2258 · Odometer rounding
Odometer reported to the nearest kilometre; distances summed from it drift over time.
BSW-2291 · 12V auxiliary discharge on remote wake
Home Assistant community integrations reported that each POST /api/cars/{vin}/systems-check wakes the vehicle's ECUs for roughly 10 minutes. Sustained polling of a parked vehicle holds the HV/ECU bus awake and discharges the 12 V auxiliary battery over several hours; the traction battery is unaffected.
A rate limit on burst polling (429 Too Many Requests) was added as a quick fix, which stops the runaway integrations that triggered the reports.
BSW-2301 · Base map needs a tile key
The companion map uses a third-party tile provider requiring an API key; without one a watermark shows but data is correct.
BSW-2333 · Enum case sensitivity
State fields (lock/climate/charging) accept lowercase values only; a capitalised value 422s.
BSW-2360 · Large fleet listing latency
The fleet list walks the customer table per car; dealers past a few thousand vehicles see multi-second responses.
BSW-2388 · Email vs username casing
Email matched case-insensitively at sign-up, username case-sensitively.
BSW-2412 · CORS preflight gaps
A few newer endpoints did not answer the OPTIONS preflight; server-to-server unaffected.
BSW-2440 · Login throttling
More than ten failed logins a minute from one source are throttled briefly.
BSW-2471 · Plate stored as free text
Registration plates are not format-validated; expect mixed spacing and casing.
BSW-2505 · Idempotency-Key ignored
The Idempotency-Key header is accepted for compatibility but not yet honoured.