{"openapi":"3.1.0","info":{"title":"VoltShare Business API","version":"1.0.0","description":"Manage your business's VoltShare charger listings from your own systems. Authenticate with an API key created on the host dashboard (Business API page): `Authorization: Bearer vsk_live_…`. Each key is limited to 120 requests per minute; an account may hold 10 active keys."},"servers":[{"url":"https://voltshare.app/api/business/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"The key and the business it belongs to."},{"name":"Stations","description":"Your charger listings."},{"name":"Availability","description":"When a station can be booked."}],"paths":{"/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"Check a key","description":"Who the key belongs to and its scopes. Any valid key may call it.","responses":{"200":{"description":"The key and its business.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Me"}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":null}},"/stations":{"get":{"tags":["Stations"],"operationId":"listStations","summary":"List stations","description":"Your stations, newest first. Pass the previous page’s `nextCursor` as `cursor` until it is `null`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"isActive","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Only live (`true`) or paused (`false`) listings."}],"responses":{"200":{"description":"A page of stations.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Station"}},"nextCursor":{"type":["string","null"]}}}}}},"400":{"description":"Bad query parameter or cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:read"},"post":{"tags":["Stations"],"operationId":"createStation","summary":"Create a station","description":"List a new charger. Geocode the address yourself and send `lat`/`lng`; the timezone is derived from them. Requires a verified email and the current Host Agreement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StationCreate"}}}},"responses":{"201":{"description":"Created.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Station"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:write"}},"/stations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Station id."}],"get":{"tags":["Stations"],"operationId":"getStation","summary":"Get a station","responses":{"200":{"description":"The station.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Station"}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:read"},"patch":{"tags":["Stations"],"operationId":"updateStation","summary":"Update a station","description":"Send only the fields to change; `null` clears an optional field. Setting one price clears the other. Pause or publish with `isActive`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StationPatch"}}}},"responses":{"200":{"description":"The updated station.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Station"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:write"},"delete":{"tags":["Stations"],"operationId":"deleteStation","summary":"Delete a station","description":"Permanent, and unlinks its charger. Only stations that were never booked can be deleted; otherwise you get `409 station_has_bookings` — PATCH `isActive: false` to take it off the map instead.","responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The station has bookings, so it can only be paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:write"}},"/stations/{id}/availability":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Station id."}],"get":{"tags":["Availability"],"operationId":"getAvailability","summary":"Get hours","description":"`data` is `null` when the station is bookable at any time.","responses":{"200":{"description":"The hours rule.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/Availability"},{"type":"null"}]}}}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:read"},"put":{"tags":["Availability"],"operationId":"setAvailability","summary":"Set hours","description":"Replace the weekly hours and blocked dates.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"responses":{"200":{"description":"The saved hours.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Availability"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:write"},"delete":{"tags":["Availability"],"operationId":"clearAvailability","summary":"Clear hours","description":"Remove the hours rule so the station is bookable at any time.","responses":{"204":{"description":"Cleared."},"401":{"description":"Missing, unknown, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account not a business host, or the key lacks the scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such station on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}},"x-required-scope":"stations:write"}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A `vsk_live_…` key from the Business API page of the host dashboard."}},"schemas":{"StationCreate":{"type":"object","additionalProperties":false,"required":["title","address","state","lat","lng","connectorType","maxPowerKw"],"properties":{"title":{"type":"string","minLength":3,"maxLength":120,"examples":["Level 2 · Bay 4"]},"description":{"type":["string","null"],"maxLength":2000},"address":{"type":"string","minLength":5,"maxLength":300,"examples":["500 Market St, San Francisco, CA 94105"]},"state":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],"description":"Two-letter US state code of the address."},"lat":{"type":"number","minimum":-90,"maximum":90,"examples":[37.7897]},"lng":{"type":"number","minimum":-180,"maximum":180,"examples":[-122.3972]},"connectorType":{"type":"string","enum":["J1772","CCS","CHAdeMO","NEMA_14_50","TESLA"]},"maxPowerKw":{"type":"number","exclusiveMinimum":0,"maximum":350,"examples":[7.4]},"pricePerHour":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per hour. Set exactly one of `pricePerHour` / `pricePerKwh`.","examples":[3.5]},"pricePerKwh":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per kWh. Only accepted in states cleared for per-kWh resale; elsewhere the request fails with `validation_error` — use `pricePerHour`."},"surgeMultiplier":{"type":["number","null"],"minimum":1,"maximum":5,"description":"Peak-hours factor on the base rate (e.g. 1.5). Surge is all-or-nothing: a multiplier above 1 needs `surgeDays`, `surgeStartTime` and `surgeEndTime`. On PATCH, `null` turns surge off and clears the window."},"surgeDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"maxItems":7,"description":"Peak days, 0 = Sunday … 6 = Saturday."},"surgeStartTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak start, station local time."},"surgeEndTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak end, station local time."},"accessType":{"type":"string","enum":["INSTANT","REQUEST"],"default":"INSTANT","description":"`INSTANT` books immediately; `REQUEST` waits for you to approve each booking."},"locationType":{"type":"string","enum":["DRIVEWAY","CURBSIDE","PARKING_LOT","GARAGE","OTHER"],"default":"DRIVEWAY"},"isActive":{"type":"boolean","default":true,"description":"Whether the listing is live on the map. `false` pauses it."},"photos":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://"},"description":"Public https image URLs."},"communityRules":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20,"description":"Rules shown to drivers before and during a session."}}},"StationPatch":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":3,"maxLength":120,"examples":["Level 2 · Bay 4"]},"description":{"type":["string","null"],"maxLength":2000},"address":{"type":"string","minLength":5,"maxLength":300,"examples":["500 Market St, San Francisco, CA 94105"]},"state":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","DC","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],"description":"Two-letter US state code of the address."},"lat":{"type":"number","minimum":-90,"maximum":90,"examples":[37.7897]},"lng":{"type":"number","minimum":-180,"maximum":180,"examples":[-122.3972]},"connectorType":{"type":"string","enum":["J1772","CCS","CHAdeMO","NEMA_14_50","TESLA"]},"maxPowerKw":{"type":"number","exclusiveMinimum":0,"maximum":350,"examples":[7.4]},"pricePerHour":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per hour. Set exactly one of `pricePerHour` / `pricePerKwh`.","examples":[3.5]},"pricePerKwh":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per kWh. Only accepted in states cleared for per-kWh resale; elsewhere the request fails with `validation_error` — use `pricePerHour`."},"surgeMultiplier":{"type":["number","null"],"minimum":1,"maximum":5,"description":"Peak-hours factor on the base rate (e.g. 1.5). Surge is all-or-nothing: a multiplier above 1 needs `surgeDays`, `surgeStartTime` and `surgeEndTime`. On PATCH, `null` turns surge off and clears the window."},"surgeDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"maxItems":7,"description":"Peak days, 0 = Sunday … 6 = Saturday."},"surgeStartTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak start, station local time."},"surgeEndTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak end, station local time."},"accessType":{"type":"string","enum":["INSTANT","REQUEST"],"default":"INSTANT","description":"`INSTANT` books immediately; `REQUEST` waits for you to approve each booking."},"locationType":{"type":"string","enum":["DRIVEWAY","CURBSIDE","PARKING_LOT","GARAGE","OTHER"],"default":"DRIVEWAY"},"isActive":{"type":"boolean","default":true,"description":"Whether the listing is live on the map. `false` pauses it."},"photos":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://"},"description":"Public https image URLs."},"communityRules":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20,"description":"Rules shown to drivers before and during a session."}}},"Station":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","minLength":3,"maxLength":120,"examples":["Level 2 · Bay 4"]},"description":{"type":["string","null"],"maxLength":2000},"address":{"type":"string","minLength":5,"maxLength":300,"examples":["500 Market St, San Francisco, CA 94105"]},"state":{"type":["string","null"]},"lat":{"type":"number","minimum":-90,"maximum":90,"examples":[37.7897]},"lng":{"type":"number","minimum":-180,"maximum":180,"examples":[-122.3972]},"connectorType":{"type":"string","enum":["J1772","CCS","CHAdeMO","NEMA_14_50","TESLA"]},"maxPowerKw":{"type":"number","exclusiveMinimum":0,"maximum":350,"examples":[7.4]},"pricePerHour":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per hour. Set exactly one of `pricePerHour` / `pricePerKwh`.","examples":[3.5]},"pricePerKwh":{"type":["number","null"],"minimum":0,"description":"Base rate in USD per kWh. Only accepted in states cleared for per-kWh resale; elsewhere the request fails with `validation_error` — use `pricePerHour`."},"surgeMultiplier":{"type":["number","null"],"minimum":1,"maximum":5,"description":"Peak-hours factor on the base rate (e.g. 1.5). Surge is all-or-nothing: a multiplier above 1 needs `surgeDays`, `surgeStartTime` and `surgeEndTime`. On PATCH, `null` turns surge off and clears the window."},"surgeDays":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"maxItems":7,"description":"Peak days, 0 = Sunday … 6 = Saturday."},"surgeStartTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak start, station local time."},"surgeEndTime":{"type":["string","null"],"pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Peak end, station local time."},"accessType":{"type":"string","enum":["INSTANT","REQUEST"],"default":"INSTANT","description":"`INSTANT` books immediately; `REQUEST` waits for you to approve each booking."},"locationType":{"type":["string","null"],"enum":["DRIVEWAY","CURBSIDE","PARKING_LOT","GARAGE","OTHER",null]},"isActive":{"type":"boolean","default":true,"description":"Whether the listing is live on the map. `false` pauses it."},"photos":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://"},"description":"Public https image URLs."},"communityRules":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20,"description":"Rules shown to drivers before and during a session."},"timeZone":{"type":"string","examples":["America/Los_Angeles"]},"status":{"type":"string","enum":["available","busy","offline"],"description":"The live badge drivers see."},"availability":{"oneOf":[{"$ref":"#/components/schemas/Availability"},{"type":"null"}]},"charger":{"type":["object","null"],"description":"The linked smart charger, if any.","properties":{"status":{"type":"string","enum":["UNCLAIMED","ACTIVE","DISABLED"]},"lastSeenAt":{"type":["string","null"],"format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Availability":{"type":"object","additionalProperties":false,"required":["dayOfWeek","startTime","endTime"],"properties":{"dayOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"minItems":1,"description":"Open days, 0 = Sunday … 6 = Saturday.","examples":[[1,2,3,4,5]]},"startTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["07:00"],"description":"Daily opening time, station local time."},"endTime":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","examples":["19:00"],"description":"Daily closing time; after `startTime`."},"blockedDates":{"type":"array","items":{"type":"string","format":"date"},"description":"Whole days the station is closed (YYYY-MM-DD).","examples":[["2026-12-25"]]}}},"Me":{"type":"object","properties":{"business":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"}}},"apiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","examples":["vsk_live_a1B2c3"]},"scopes":{"type":"array","items":{"type":"string","enum":["stations:read","stations:write"]}},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_api_key","api_key_revoked","api_key_expired","business_account_required","insufficient_scope","email_unverified","host_agreement_required","invalid_json","unknown_field","validation_error","invalid_cursor","not_found","station_has_bookings","rate_limited"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}