Vehicles

See Vehicles. A vehicle belongs to one space, your Personal space or an organization's, and routes take that space in their path. A key needs vehicles:read to read, vehicles:write to change settings, places and tariffs, and vehicles:control to send commands; each command also needs the matching capability on that vehicle. A vehicle's position is only in answers where its sharing allows it.

GET /v1/vehicles/tesla/callback

Tesla's registered redirect after sign-in (no token): spends the one-time state, hands the code to Vehicles' worker and redirects the browser to the app's finish page with a ticket or a reason. Never shows a page of its own.

Auth: none

Errors

GET /v1/platform/vehicles/pictures

The switch, every rule (with what is wrong with one that fails validation, and overlaps) and the misses.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
  rules: {
    invalid?: string
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    model?: string
    defaults?: {
      trim?: string[]
      paint?: string[]
      wheels?: string[]
      roof?: string[]
      spoiler?: string[]
      exteriorTrim?: string[]
    }
  }[]
  warnings: {
    ruleId: string
    other: string
    message: string
  }[]
  misses: {
    carType: string
    slot: string
    value: string
    count: number
    firstSeen: number
    lastSeen: number
  }[]
}

Errors

GET /v1/platform/vehicles/pictures/rules

The picture rules, and the warnings about them (platform staff).

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  rules: {
    invalid?: string
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    model?: string
    defaults?: {
      trim?: string[]
      paint?: string[]
      wheels?: string[]
      roof?: string[]
      spoiler?: string[]
      exteriorTrim?: string[]
    }
  }[]
  warnings: {
    ruleId: string
    other: string
    message: string
  }[]
}

Errors

PUT /v1/platform/vehicles/pictures/rules/:ruleId

Writes a rule (creating or replacing it by id). Raises rev.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Request body

Also checked: Unknown fields are rejected.

Response 200

{
  rule: {
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    model?: string
    defaults?: {
      trim?: string[]
      paint?: string[]
      wheels?: string[]
      roof?: string[]
      spoiler?: string[]
      exteriorTrim?: string[]
    }
  }
  warnings: {
    ruleId: string
    other: string
    message: string
  }[]
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}

Errors

DELETE /v1/platform/vehicles/pictures/rules/:ruleId

Removes a picture rule. Raises rev.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  ok: true
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}

Errors

GET /v1/platform/vehicles/pictures/misses

The values no rule covers, most recent first: what to map next.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  misses: {
    carType: string
    slot: string
    value: string
    count: number
    firstSeen: number
    lastSeen: number
  }[]
}

Errors

DELETE /v1/platform/vehicles/pictures/misses

Dismisses a miss (?carType=&slot=&value=); audited.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  ok: true
}

Errors

GET /v1/platform/vehicles/pictures/switch

Whether car pictures are on.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}

Errors

PUT /v1/platform/vehicles/pictures/switch

Turns pictures on or off. Off: no picture anywhere and no fetch, within a minute (the API's cache).

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Request body

Also checked: Unknown fields are rejected.

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}

Errors

POST /v1/platform/vehicles/pictures/refresh-all

Refresh all: new keys in the bucket (a new epoch), fetched as cars are seen, and every car resolved again.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}

Errors

POST /v1/platform/vehicles/pictures/preview

Resolves submitted values through the worker: { year?, config: { carType, exteriorColor, … }, include?: [ruleId] } (include: disabled rows to use for this preview only). ready carries signed links on our CDN for each view, the model and the codes it sent; every other outcome carries a message.

Auth: user access token or platform agent key · Scope: platform:admin in the platform organization

Request body

Also checked: Unknown fields are rejected.

Response 200

{
  model?: string
  codes?: string[]
  misses?: {
    carType: string
    slot: string
    value: string
  }[]
  outcome: "busy" | "no_rule" | "mapping" | "fetch" | "timeout"
  message: string
}
| {
  views: {
    "3qtr"?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
    side?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
  }
  approximate?: string[]
  outcome: string
  model: string
  codes: string[]
}

Errors

POST /v1/me/vehicles/connections/tesla/authorize

Starts connecting your Tesla account: send the consent you gave (each data category, and precise location as its own choice); returns Tesla's sign-in url and a browserValue for the app to keep as an HttpOnly cookie and send back to finish. Only from the Vehicles and phone apps.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  url: string
  browserValue: string
  expiresAt: number
}

Errors

POST /v1/me/vehicles/connections/tesla/finish

Finishes the connection with the ticket from the redirect and the browserValue. Kept only for the person and browser that started it, otherwise the tokens are discarded. 202 pending while the exchange is still running (ask again in a second).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  connection: {
    connectionId: string
    provider: "tesla"
    status: "ok" | "revoked" | "reconnect" | "disconnecting"
    region: "na-apac" | "eu"
    scopes: string[]
    location: boolean
    createdAt: number
    createdBy?: string
    lastRefreshAt?: number
    notice?: string
  }
  returnTo?: string
  reconnected: boolean
  sameAccount: boolean
}

Response 202

{
  status: string
}

Errors

GET /v1/me/vehicles/connections

Your Tesla connections: status (ok, reconnect), region, granted scopes and whether precise location is on. Never a token.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  connections: {
    connectionId: string
    provider: "tesla"
    status: "ok" | "revoked" | "reconnect" | "disconnecting"
    region: "na-apac" | "eu"
    scopes: string[]
    location: boolean
    createdAt: number
    createdBy?: string
    lastRefreshAt?: number
    notice?: string
  }[]
}

Errors

DELETE /v1/me/vehicles/connections/:connectionId

Disconnects a Tesla account: its tokens are removed at once and its telemetry stops. Returns Tesla's page for withdrawing the app's access there too (consentUrl).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 200

{
  consentUrl: string
}

Errors

GET /v1/me/vehicles

The garage: the cars of this space the caller holds anything on, each with their capabilities and a status summary ({ vehicles }). In a Personal space also the cars shared with them. An organisation's members see the cars they have been granted, a fleet admin all of them.

Auth: user access token or platform agent key · Scopes: vehicles:read (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}

Errors

GET /v1/me/vehicles/connections/:connectionId/vehicles

Every car Tesla shows for a connection, and which can be added: status available, claimed_here, claimed_elsewhere or unavailable, the last two with a reason in words ({ vehicles }; asks Tesla, so it is limited and 503 where that isn't wired). For a person in the app, a car in another space they manage, which this account owns, is movable with that space's fromSpaceName and fromSpaceKind: a claim moves it here. Of any other space nothing is said.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 200

{
  vehicles: {
    fromSpaceKind?: "org" | "personal"
    fromSpaceName?: string
    movable?: boolean
    providerVehicleId?: string
    reason?: string
    vehicleId?: string
    vin: string
    name?: string
    model?: string
    accessType?: "OWNER" | "DRIVER"
    state?: string
    status: "unavailable" | "available" | "claimed_here" | "claimed_elsewhere"
  }[]
}

Errors

POST /v1/me/vehicles/connections/:connectionId/sync

Rediscover a connection's cars: queued for the worker (the API never calls Tesla), 202. List them again a moment later.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 202

{
  queued: true
}

Errors

POST /v1/me/vehicles/claim

Adds a car the connection lists to this space and starts key pairing. The VIN is only ever accepted if the connection lists it now. 201 { outcome: "claimed" | "took_over", vehicle }, 200 for exists and moved, and 409 grant_request with the holder's vehicleId when someone else holds the car and this account may not take it.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  outcome: "exists" | "moved"
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
}

Response 201

{
  outcome: string
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
  ended: {
    vehicleId: string
  }
}
| {
  outcome: string
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
}

Errors

GET /v1/me/vehicles/api-access

Whether API keys (yours, and your organizations' keys made by you) may use your Personal Vehicles. Off until you turn it on.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  enabled: boolean
}

Errors

PUT /v1/me/vehicles/api-access

Turns API key access to your Personal Vehicles on or off. Only you, in the Vehicles app.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  enabled: boolean
}

Errors

GET /v1/me/vehicles/display

The display units you chose, the same in every space: distance (km, mi), temperature (C, F), pressure (kPa, bar, psi), efficiency (Wh/km, km/kWh, Wh/mi, mi/kWh), battery (percent, range) and map (standard, satellite). Only what you chose; the rest follows your language. Every other answer stays metric.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  display: {
    distance?: "km" | "mi"
    temperature?: "C" | "F"
    pressure?: "kPa" | "bar" | "psi"
    efficiency?: "Wh/km" | "km/kWh" | "Wh/mi" | "mi/kWh"
    battery?: "range" | "percent"
    map?: "standard" | "satellite"
  }
}

Errors

PUT /v1/me/vehicles/display

Replaces your display units ({ display: { … } }); {} goes back to your language's. Only you, in the Vehicles or phone app.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  display: {
    distance?: "km" | "mi"
    temperature?: "C" | "F"
    pressure?: "kPa" | "bar" | "psi"
    efficiency?: "Wh/km" | "km/kWh" | "Wh/mi" | "mi/kWh"
    battery?: "range" | "percent"
    map?: "standard" | "satellite"
  }
}

Errors

GET /v1/me/vehicles/profile

The space's units, currency, default tariff and the trim around a home place on shared routes.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
}

Errors

PUT /v1/me/vehicles/profile

Changes those that are given; null clears the default tariff or the trim. The default tariff is one of the space's.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
}

Errors

GET /v1/me/vehicles/places

The space's charging places (a centre and a radius in metres), by name.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  places: {
    placeId: string
    name?: string
    kind: "home" | "other" | "work"
    lat: number
    lon: number
    radiusM: number
    tariffId: null | string
  }[]
}

Errors

POST /v1/me/vehicles/places

Adds a charging place: a name, a centre and a radius in metres (default 100), a kind and a tariff if it has one. 201; 409 limit_reached at the space's limit.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 201

{
  placeId: string
  name: string
  kind: "home" | "other" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}

Errors

PATCH /v1/me/vehicles/places/:placeId

Changes the fields given on a place; tariffId: null clears its tariff.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  placeId: string
  name?: string
  kind: "home" | "other" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}

Errors

DELETE /v1/me/vehicles/places/:placeId

Removes a place; an automation that names it stops it, so the place stays until that automation is changed (409).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 204 with no body.

Errors

GET /v1/me/vehicles/tariffs/plans

Retailer plans for a postcode, from the AER's reference data (cached a day; the NECF states only). plans is empty for a postcode no plan serves.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  fetchedAt: string
  truncated?: true
  postcode: string
  state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
  retailer: string
  plans: {
    planId: string
    name: string
    brand: string
    customerType: string
    type: string
  }[]
}

Errors

GET /v1/me/vehicles/tariffs

The space's tariffs, by name.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  tariffs: {
    [key: string]: unknown
    [key: number]: unknown
  }[]
}

Errors

POST /v1/me/vehicles/tariffs

Adds a tariff: flat, or time of use with windows that tile the day for weekdays and weekends. 201; 409 limit_reached.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: A flat tariff has flatTenthsCents; a time-of-use tariff has zone and periods. Sharing the supply charge needs supplyCentsPerDay.

Response 201

{
  tariffId: string
  name: string
  kind: "flat" | "tou"
  supplyShare: boolean
  flatTenthsCents?: number
  zone?: string
  periods?: {
    name: "peak" | "shoulder" | "offpeak"
    days: "all" | "weekday" | "weekend"
    from: string
    to: string
    tenthsCents: number
  }[]
  exportTenthsCents?: number
  supplyCentsPerDay?: number
}

Errors

PUT /v1/me/vehicles/tariffs/:tariffId

Replaces a tariff with the one given.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: A flat tariff has flatTenthsCents; a time-of-use tariff has zone and periods. Sharing the supply charge needs supplyCentsPerDay.

Response 200

{
  tariffId: string
  name: string
  kind: "flat" | "tou"
  supplyShare: boolean
  flatTenthsCents?: number
  zone?: string
  periods?: {
    name: "peak" | "shoulder" | "offpeak"
    days: "all" | "weekday" | "weekend"
    from: string
    to: string
    tenthsCents: number
  }[]
  exportTenthsCents?: number
  supplyCentsPerDay?: number
}

Errors

DELETE /v1/me/vehicles/tariffs/:tariffId

Removes a tariff; the default tariff and a place that uses it keep it from going (409).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 204 with no body.

Errors

GET /v1/me/vehicles/geofences

The space's geofences: a circle (metres) or a polygon of up to 500 points. Enter and leave are told with the fence's name, never its coordinates.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  geofences: {
    fenceId: string
    name?: string
    shape: {
      type: "circle"
      lat: number
      lon: number
      radiusM: number
    } | {
      type: "polygon"
      points: number[][]
    }
    enabled: boolean
    notifyOn: "both" | "leave" | "enter"
  }[]
}

Errors

POST /v1/me/vehicles/geofences

Adds a geofence: a circle or a polygon, sealed at rest. 201; 400 for an antimeridian crossing; 409 limit_reached.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 201

{
  fenceId: string
  name: string
  shape: {
    type: "circle"
    lat: number
    lon: number
    radiusM: number
  } | {
    type: "polygon"
    points: number[][]
  }
  enabled: boolean
  notifyOn: "both" | "leave" | "enter"
}

Errors

PATCH /v1/me/vehicles/geofences/:fenceId

Changes the fields given on a geofence.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  fenceId: string
  name?: string
  shape: {
    type: "circle"
    lat: number
    lon: number
    radiusM: number
  } | {
    type: "polygon"
    points: number[][]
  }
  enabled: boolean
  notifyOn: "both" | "leave" | "enter"
}

Errors

DELETE /v1/me/vehicles/geofences/:fenceId

Removes a geofence; an automation triggered by it keeps it from going (409).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 204 with no body.

Errors

GET /v1/me/vehicles/automations

The space's automations: a trigger, conditions and up to five actions on the cars named, run with the creator's capabilities. The engine that runs them is not built, so these are stored and shown, and none fires yet.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  automations: {
    [key: string]: unknown
    [key: number]: unknown
  }[]
}

Errors

POST /v1/me/vehicles/automations

Adds an automation. Command actions follow the confirmation table: a tap is stored, a hold needs a fresh step-up, a step-up command is refused. 201.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 201

{
  automationId: string
  name: string
  createdBy: string
  enabled: boolean
  vehicleIds: string[]
  trigger: {
    type: "schedule"
    at: string
    days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
    zone: string
  } | {
    type: "once"
    at: string
  } | {
    type: "geofence"
    fenceId: string
    on: "leave" | "enter"
  } | {
    type: "plugged"
    on: "out" | "in"
  } | {
    type: "charge_reached"
    socPct: number
  } | {
    type: "soc_below"
    socPct: number
  } | {
    type: "outside_temp"
    aboveC?: number
    belowC?: number
  } | {
    type: "drive_ended"
  } | {
    type: "left_unlocked"
    minutes: number
  }
  conditions: {
    insidePlaceId?: string
    window?: {
      from: string
      to: string
      zone: string
    }
    socMin?: number
    socMax?: number
    plugged?: boolean
    nobodyInside?: boolean
  }
  actions: {
    type: "command"
    command: string
    args: {
      [key: string]: unknown
    }
    confirmedAt?: number
  } | {
    type: "notify"
    message: string
    confirmedAt?: number
  }[]
  createdAt: number
  updatedAt: number
}

Errors

PATCH /v1/me/vehicles/automations/:automationId

Changes an automation. Only its creator changes the cars, trigger, conditions or actions (403 not_creator); another admin may switch or rename it.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  [key: string]: unknown
}

Errors

DELETE /v1/me/vehicles/automations/:automationId

Removes an automation. 204.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 204 with no body.

Errors

POST /v1/orgs/:orgId/vehicles/connections/tesla/authorize

Starts connecting a Tesla account to the organization (owners and admins, from the app): returns Tesla's sign-in url and the browserValue to keep and send back to finish.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  url: string
  browserValue: string
  expiresAt: number
}

Errors

POST /v1/orgs/:orgId/vehicles/connections/tesla/finish

Finishes the organization's Tesla connection with the redirect's ticket and the browserValue; 202 pending while the exchange is running.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  connection: {
    connectionId: string
    provider: "tesla"
    status: "ok" | "revoked" | "reconnect" | "disconnecting"
    region: "na-apac" | "eu"
    scopes: string[]
    location: boolean
    createdAt: number
    createdBy?: string
    lastRefreshAt?: number
    notice?: string
  }
  returnTo?: string
  reconnected: boolean
  sameAccount: boolean
}

Response 202

{
  status: string
}

Errors

GET /v1/orgs/:orgId/vehicles/connections

The organization's Tesla connections: status, region, granted scopes and whether precise location is on. Never a token.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  connections: {
    connectionId: string
    provider: "tesla"
    status: "ok" | "revoked" | "reconnect" | "disconnecting"
    region: "na-apac" | "eu"
    scopes: string[]
    location: boolean
    createdAt: number
    createdBy?: string
    lastRefreshAt?: number
    notice?: string
  }[]
}

Errors

DELETE /v1/orgs/:orgId/vehicles/connections/:connectionId

Disconnects the organization's Tesla account: tokens removed at once, telemetry stopped; returns Tesla's page for withdrawing access (consentUrl).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 200

{
  consentUrl: string
}

Errors

GET /v1/orgs/:orgId/vehicles

The garage: the cars of this space the caller holds anything on, each with their capabilities and a status summary ({ vehicles }). In a Personal space also the cars shared with them. An organisation's members see the cars they have been granted, a fleet admin all of them.

Auth: user access token or platform agent key · Scopes: vehicles:read (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}

Errors

GET /v1/orgs/:orgId/vehicles/connections/:connectionId/vehicles

Every car Tesla shows for a connection, and which can be added: status available, claimed_here, claimed_elsewhere or unavailable, the last two with a reason in words ({ vehicles }; asks Tesla, so it is limited and 503 where that isn't wired). For a person in the app, a car in another space they manage, which this account owns, is movable with that space's fromSpaceName and fromSpaceKind: a claim moves it here. Of any other space nothing is said.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 200

{
  vehicles: {
    fromSpaceKind?: "org" | "personal"
    fromSpaceName?: string
    movable?: boolean
    providerVehicleId?: string
    reason?: string
    vehicleId?: string
    vin: string
    name?: string
    model?: string
    accessType?: "OWNER" | "DRIVER"
    state?: string
    status: "unavailable" | "available" | "claimed_here" | "claimed_elsewhere"
  }[]
}

Errors

POST /v1/orgs/:orgId/vehicles/connections/:connectionId/sync

Rediscover a connection's cars: queued for the worker (the API never calls Tesla), 202. List them again a moment later.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 202

{
  queued: true
}

Errors

POST /v1/orgs/:orgId/vehicles/claim

Adds a car the connection lists to this space and starts key pairing. The VIN is only ever accepted if the connection lists it now. 201 { outcome: "claimed" | "took_over", vehicle }, 200 for exists and moved, and 409 grant_request with the holder's vehicleId when someone else holds the car and this account may not take it.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 200

{
  outcome: "exists" | "moved"
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
}

Response 201

{
  outcome: string
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
  ended: {
    vehicleId: string
  }
}
| {
  outcome: string
  vehicle: {
    vehicleId: string
    model?: string
    trim?: string
    vinTail: string
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
  }
}

Errors

GET /v1/orgs/:orgId/vehicles/profile

The space's units, currency, default tariff and the trim around a home place on shared routes.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
}

Errors

PUT /v1/orgs/:orgId/vehicles/profile

Changes those that are given; null clears the default tariff or the trim. The default tariff is one of the space's.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
}

Errors

GET /v1/orgs/:orgId/vehicles/places

The space's charging places (a centre and a radius in metres), by name.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  places: {
    placeId: string
    name?: string
    kind: "home" | "other" | "work"
    lat: number
    lon: number
    radiusM: number
    tariffId: null | string
  }[]
}

Errors

POST /v1/orgs/:orgId/vehicles/places

Adds a charging place: a name, a centre and a radius in metres (default 100), a kind and a tariff if it has one. 201; 409 limit_reached at the space's limit.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Response 201

{
  placeId: string
  name: string
  kind: "home" | "other" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}

Errors

PATCH /v1/orgs/:orgId/vehicles/places/:placeId

Changes the fields given on a place; tariffId: null clears its tariff.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body

Also checked: Say what to change.

Response 200

{
  placeId: string
  name?: string
  kind: "home" | "other" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}

Errors

DELETE /v1/orgs/:orgId/vehicles/places/:placeId

Removes a place; an automation that names it stops it, so the place stays until that automation is changed (409).

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Response 204 with no body.

Errors

GET /v1/orgs/:orgId/vehicles/tariffs/plans

Retailer plans for a postcode, from the AER's reference data (cached a day; the NECF states only). plans is empty for a postcode no plan serves.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  fetchedAt: string
  truncated?: true
  postcode: string
  state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
  retailer: string
  plans: {
    planId: string
    name: string
    brand: string
    customerType: string
    type: string
  }[]
}

Errors

GET /v1/orgs/:orgId/vehicles/tariffs

The space's tariffs, by name.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:read (when actor.type === "user")

Response 200

{
  tariffs: {
    [key: string]: unknown
    [key: number]: unknown
  }[]
}

Errors

POST /v1/orgs/:orgId/vehicles/tariffs

Adds a tariff: flat, or time of use with windows that tile the day for weekdays and weekends. 201; 409 limit_reached.

Auth: user access token or platform agent key · Scopes: vehicles:admin (when orgId), vehicles:write (when actor.type === "user")

Request body