Docs
Developer Portal

API reference

Vehicles

Your Tesla vehicles and your organization's fleet: live state, commands, drives, charging, parked periods, keys and drivers, places, tariffs and sharing.
Read the Guide
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

  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/tesla/callback'
Send it from this page with your session or a key.
GET/v1/vehicles/shared/drives/:token

The drive a share link opens, with nobody signed in: its route, distance, times and charts as the link allows (ends cut, speeds left out), and never places, the driver, tags or events, nor more than the car's privacy shows everyone and its maker sees now (speeds left out where either hides them). 404 for anything a link doesn't open, whatever the reason: ended, revoked, or a drive the car's privacy or its maker's access no longer lets out.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

Errors

  • 404This link doesn't open a drive. It may have ended.
  • 429Too many requests. Try again later.
curl 'https://api.cactive.com.au/v1/vehicles/shared/drives/{token}'
Send it from this page with your session or a key.

Response 200

{
  photos?: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    cardUrl?: string
  }[]
  points: {
    t?: number
    lat: number
    lon: number
    speedKmh?: number
  }[]
  untimed?: boolean
  hideEnds: boolean
  hideSpeed: boolean
  maxSpeedKmh?: number
  avgMovingSpeedKmh?: number
  startedAt: string
  endedAt?: string
  distanceKm?: number
  energyKwh?: number
  whPerKm?: number
}
GET/v1/vehicles/shared/reviews/:token

The Year in Review a share link opens, with nobody signed in: the car's name and the range's numbers from what the car shows everyone, costs and saved places only if the link was made with them, and no drive ids.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

Errors

  • 404This link doesn't open a review. It may have ended.
  • 429Too many requests. Try again later.
curl 'https://api.cactive.com.au/v1/vehicles/shared/reviews/{token}'
Send it from this page with your session or a key.

Response 200

{
  photos?: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    cardUrl?: string
  }[]
  review: {
    from: string
    to: string
    timeZone?: string
    drives: number
    distanceKm: number
    drivingMinutes: number
    energyKwh: number
    climbM: number
    assistedKm?: number
    assistedOfKm?: number
    charges: number
    kwhAdded: number
    fastKwh: number
    costCents?: number
    savedCents?: number
    co2SavedKg?: number
    longest?: {
      tripId?: string
      startedAt: string
      distanceKm: number
      from?: string
      to?: string
      whPerKm?: number
    }
    busiestDay?: {
      day: string
      distanceKm: number
      drives: number
    }
    efficiencyBest?: {
      tripId?: string
      startedAt: string
      distanceKm: number
      from?: string
      to?: string
      whPerKm?: number
    }
    topSpeedKmh?: number
    cruise?: {
      kmh: number
      mph: number
    }
    places?: {
      name: string
      visits: number
    }[]
    months: {
      month: string
      distanceKm: number
      drives: number
    }[]
    music?: {
      minutes: number
      drivingMinutes: number
      drives: number
      artists: {
        name: string
        detail?: string
        minutes: number
        plays: number
      }[]
      songs: {
        name: string
        detail?: string
        minutes: number
        plays: number
      }[]
      stations: {
        name: string
        detail?: string
        minutes: number
        plays: number
      }[]
      sources: {
        name: string
        detail?: string
        minutes: number
        plays: number
      }[]
    }
    truncated?: true
  }
  picture?: {
    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?: true
    source: "photo" | "tesla" | "appearance"
  }
  name: string
  model?: string
}
GET/v1/platform/vehicles/pictures

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl 'https://api.cactive.com.au/v1/platform/vehicles/pictures' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
  rules: {
    invalid?: string
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "interior" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    label?: string
    approximate?: boolean
    model?: string
    defaults?: {
      trim?: string[]
      interior?: 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
    suggestion?: {
      codes: string[]
      from: "value" | "row"
      ruleId?: string
      fromYear?: number
      toYear?: number
      outcome: "rendered" | "refused" | "no_effect"
      at: number
    }
  }[]
}
GET/v1/platform/vehicles/pictures/rules

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl 'https://api.cactive.com.au/v1/platform/vehicles/pictures/rules' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  rules: {
    invalid?: string
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "interior" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    label?: string
    approximate?: boolean
    model?: string
    defaults?: {
      trim?: string[]
      interior?: string[]
      paint?: string[]
      wheels?: string[]
      roof?: string[]
      spoiler?: string[]
      exteriorTrim?: string[]
    }
  }[]
  warnings: {
    ruleId: string
    other: string
    message: string
  }[]
}
PUT/v1/platform/vehicles/pictures/rules/:ruleId

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Path parameters

  • ruleId

    Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes), an issue automation rule (rul_…) or a Mirage AutoMod rule (mar_…).

Request body

  • carTypestringrequired

    Up to 40 characters.

  • fromYearintegeror null
  • toYearintegeror null
  • slotstringrequired

    Up to 20 characters.

  • valuestringrequired

    Up to 200 characters.

  • codesstring[]required

    Up to 50 items. Each up to 20 characters.

  • enabledboolean

    Default true.

  • notestringor null

    Up to 1,000 characters.

  • labelstringor null

    Up to 200 characters.

  • approximatebooleanor null
  • modelstringor null

    Up to 20 characters.

  • defaultsobjector null

    Keys up to 20 characters. Values: string[] (up to 50 items, each up to 20 characters).

Also checked: Unknown fields are rejected.

Errors

  • 503The platform table isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/platform/vehicles/pictures/rules/{ruleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "carType": "example",
    "slot": "example",
    "value": "example",
    "codes": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  rule: {
    ruleId: string
    carType: string
    fromYear?: number
    toYear?: number
    slot: "trim" | "base" | "interior" | "paint" | "wheels" | "roof" | "spoiler" | "exteriorTrim"
    value: string
    codes: string[]
    enabled: boolean
    note?: string
    label?: string
    approximate?: boolean
    model?: string
    defaults?: {
      trim?: string[]
      interior?: 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
  }
}
DELETE/v1/platform/vehicles/pictures/rules/:ruleId

Removes a picture rule. Raises rev.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Path parameters

  • ruleId

    Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes), an issue automation rule (rul_…) or a Mirage AutoMod rule (mar_…).

Errors

  • 404Rule not found
  • 503The platform table isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/platform/vehicles/pictures/rules/{ruleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  ok: true
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}
GET/v1/platform/vehicles/pictures/misses

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl 'https://api.cactive.com.au/v1/platform/vehicles/pictures/misses' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  misses: {
    carType: string
    slot: string
    value: string
    count: number
    firstSeen: number
    lastSeen: number
    suggestion?: {
      codes: string[]
      from: "value" | "row"
      ruleId?: string
      fromYear?: number
      toYear?: number
      outcome: "rendered" | "refused" | "no_effect"
      at: number
    }
  }[]
}
DELETE/v1/platform/vehicles/pictures/misses

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/platform/vehicles/pictures/misses' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  ok: true
}
GET/v1/platform/vehicles/pictures/switch

Whether car pictures are on.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl 'https://api.cactive.com.au/v1/platform/vehicles/pictures/switch' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}
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
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Request body

  • enabledbooleanrequired

Also checked: Unknown fields are rejected.

Errors

  • 503The platform table isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/platform/vehicles/pictures/switch' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'
Send it from this page with your session or a key.

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}
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
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Errors

  • 503The platform table isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/platform/vehicles/pictures/refresh-all' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  switch: {
    enabled: boolean
    rev: number
    epoch: number
  }
}
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
A person's token or an API key, as Authorization: Bearer.
Scope
platform:admin in the platform organisation
Get an API key

Request body

  • yearinteger
  • configobjectrequired

    Keys up to 40 characters. Values: string (up to 200 characters).

  • includestring[]

    Up to 20 items. Each up to 80 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403The preview is for people in Admin.
  • 503The platform table isn't available here.
  • 503The picture CDN isn't on here, so there is nothing to show a preview from.
curl -X POST 'https://api.cactive.com.au/v1/platform/vehicles/pictures/preview' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "config": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  model?: string
  codes?: string[]
  misses?: {
    carType: string
    slot: string
    value: string
  }[]
  outcome: "fetch" | "busy" | "no_rule" | "mapping" | "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[]
}
GET/v1/me/vehicles/requestable

An org's cars by id and name, for its active, non-guest members to ask for; nothing else about them.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/requestable' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    vehicleId: string
    name: string
  }[]
}
GET/v1/me/vehicles/sentry-force

Forced Sentry Mode on each of the space's cars: which are forced, and their floors.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    vehicleId: string
    name: string
    force: null | {
      since: number
      by: string
      floorPct: number
      pausedLowAt: null | number
      lastAt: null | number
      failedAt: null | number
    }
  }[]
}
PUT/v1/me/vehicles/sentry-force

Forces Sentry Mode on for every car of the space, each turned on now (queued).

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • floorPctinteger

    Default 20. 5–80.

Also checked: Unknown fields are rejected.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/me/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "floorPct": 20
  }'
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}
DELETE/v1/me/vehicles/sentry-force

Lifts forced Sentry Mode on every car of the space. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • returnTostring

    Up to 300 characters.

  • client"phone"
  • reconnectstring

    Up to 80 characters.

  • consentobjectrequired
  • consent.categories("vehicle_state" | "commands" | "charging")[]required
  • consent.locationbooleanrequired

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/connections/tesla/authorize' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "consent": {
      "categories": [
        "vehicle_state"
      ],
      "location": true
    }
  }'
Send it from this page with your session or a key.

Response 200

{
  url: string
  browserValue: string
  expiresAt: number
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • ticketstringrequired

    1–200 characters.

  • browserValuestringrequired

    1–200 characters.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/connections/tesla/finish' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": "example",
    "browserValue": "example"
  }'
Send it from this page with your session or a key.

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
}
GET/v1/me/vehicles/connections

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/connections' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/connections/{connectionId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  consentUrl: string
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:read (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 400Not a connection id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/connections/{connectionId}/vehicles' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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"
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 400Not a connection id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Connection not found
  • 409Reconnect this Tesla account first.
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/connections/{connectionId}/sync' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  queued: true
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • connectionIdstringrequired
  • vinstringrequired

    Matches ^[A-HJ-NPR-Z0-9]{17}$. Trimmed. Uppercased.

  • namestring

    1–60 characters. Trimmed.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 409Someone else holds this car. Ask them to share it with you.
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/claim' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "connectionId": "<connectionId>",
    "vin": "example"
  }'
Send it from this page with your session or a key.

Response 200

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

Response 201

{
  outcome: string
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
  ended: {
    vehicleId: string
  }
}
| {
  outcome: string
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
}
POST/v1/me/vehicles/manual

Adds a car logged by hand (docs/vehicles/manual.md): any make and fuel, no Tesla connection. 201 { vehicle }; with odometerKm, its first odometer reading is logged too. The space's own (as a claim), from the app or a key; audited as vehicle.add.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • namestringrequired

    1–60 characters.

  • makestringrequired

    1–40 characters.

  • modelstring

    Up to 60 characters.

  • yearinteger
  • fuel"electric" | "petrol" | "diesel" | "hybrid" | "plugin_hybrid"required
  • platestring

    Up to 12 characters.

  • odometerKmnumber

    0–2000000.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/manual' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "make": "example",
    "fuel": "electric"
  }'
Send it from this page with your session or a key.

Response 201

{
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 403Change this in the Vehicles app.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/api-access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  enabled: boolean
}
PUT/v1/me/vehicles/api-access

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • enabledbooleanrequired

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/me/vehicles/api-access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'
Send it from this page with your session or a key.

Response 200

{
  enabled: boolean
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/display' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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"
    shortcuts?: ("charging" | "sentry" | "port" | "trunk" | "locks" | "climate" | "frunk" | "windows" | "defrost" | "homelink" | "flash" | "honk")[]
    listEfficiency?: boolean
    confirmPrompts?: boolean
    roads?: boolean
  }
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • displayobjectrequired
  • display.distance"km" | "mi"
  • display.temperature"C" | "F"
  • display.pressure"kPa" | "bar" | "psi"
  • display.efficiency"Wh/km" | "km/kWh" | "Wh/mi" | "mi/kWh"
  • display.battery"percent" | "range"
  • display.map"standard" | "satellite"
  • display.shortcuts("locks" | "climate" | "frunk" | "trunk" | "windows" | "port" | "charging" | "sentry" | "defrost" | "homelink" | "flash" | "honk")[]

    Up to 6 items.

  • display.listEfficiencyboolean
  • display.confirmPromptsboolean
  • display.roadsboolean

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/me/vehicles/display' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "display": {
      "distance": "km",
      "temperature": "C",
      "pressure": "kPa"
    }
  }'
Send it from this page with your session or a key.

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"
    shortcuts?: ("charging" | "sentry" | "port" | "trunk" | "locks" | "climate" | "frunk" | "windows" | "defrost" | "homelink" | "flash" | "honk")[]
    listEfficiency?: boolean
    confirmPrompts?: boolean
    roads?: boolean
  }
}
GET/v1/me/vehicles/profile

The space's units, currency, default tariff, the trim around a home place on shared routes, and the petrol car drives are compared with.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
  fuelLPer100Km: null | number
  fuelCentsPerL: null | number
}
PUT/v1/me/vehicles/profile

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • units"metric" | "imperial"
  • currencystring

    Matches ^[A-Z]{3}$.

  • defaultTariffIdstringor null
  • homeTrimRadiusMintegeror null

    0–2000.

  • fuelLPer100Kmnumberor null

    1–40.

  • fuelCentsPerLintegeror null

    1–100000.

Also checked: Say what to change.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X PUT 'https://api.cactive.com.au/v1/me/vehicles/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "units": "metric",
    "currency": "example",
    "defaultTariffId": "<defaultTariffId>"
  }'
Send it from this page with your session or a key.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
  fuelLPer100Km: null | number
  fuelCentsPerL: null | number
}
GET/v1/me/vehicles/places

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  places: {
    placeId: string
    name?: string
    kind: "other" | "home" | "work"
    lat: number
    lon: number
    radiusM: number
    tariffId: null | string
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • nameany JSONrequired
  • kindany JSON

    Default "other".

  • latnumberrequired

    -90–90.

  • lonnumberrequired

    -180–180.

  • radiusMany JSON

    Default 100.

  • tariffIdany JSON

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "lat": 1,
    "lon": 1
  }'
Send it from this page with your session or a key.

Response 201

{
  placeId: string
  name: string
  kind: "other" | "home" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}
PATCH/v1/me/vehicles/places/:placeId

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • placeId

    A place's id: in Maps a saved place (plc_…), in Vehicles a space's charging place (vpl_…).

Request body

  • nameany JSON
  • kindany JSON
  • latnumber

    -90–90.

  • lonnumber

    -180–180.

  • radiusMany JSON
  • tariffIdany JSON

Also checked: Say what to change.

Errors

  • 400Not a place id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Place not found
  • 404Tariff not found
curl -X PATCH 'https://api.cactive.com.au/v1/me/vehicles/places/{placeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": {},
    "lat": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  placeId: string
  name?: string
  kind: "other" | "home" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • placeId

    A place's id: in Maps a saved place (plc_…), in Vehicles a space's charging place (vpl_…).

Errors

  • 400Not a place id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Place not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/places/{placeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Query parameters

  • postcodestringrequired

    Matches ^\d{4}$.

  • retailerstringrequired

    Matches ^[a-z0-9][a-z0-9-]{1,38}$.

Errors

  • 400Not an Australian postcode.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/tariffs/plans?postcode=example&retailer=example' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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
  }[]
}
GET/v1/me/vehicles/tariffs

The space's tariffs, by name.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/tariffs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  tariffs: {
    [key: string]: unknown
    [key: number]: unknown
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • nameany JSONrequired
  • kind"flat" | "tou"required
  • flatTenthsCentsinteger

    0–10000.

  • zonestring

    Up to 64 characters.

  • periodsobject[]

    1–12 items.

  • periods[].name"peak" | "shoulder" | "offpeak"required
  • periods[].days"weekday" | "weekend" | "all"required
  • periods[].fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tostring | "24:00"required

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tenthsCentsintegerrequired

    0–10000.

  • exportTenthsCentsinteger

    0–10000.

  • supplyCentsPerDayinteger

    0–10000.

  • supplyShareboolean

    Default false.

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

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/tariffs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": "flat"
  }'
Send it from this page with your session or a key.

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
}
PUT/v1/me/vehicles/tariffs/:tariffId

Replaces a tariff with the one given.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • tariffId

    A tariff's id (vtf_…).

Request body

  • nameany JSONrequired
  • kind"flat" | "tou"required
  • flatTenthsCentsinteger

    0–10000.

  • zonestring

    Up to 64 characters.

  • periodsobject[]

    1–12 items.

  • periods[].name"peak" | "shoulder" | "offpeak"required
  • periods[].days"weekday" | "weekend" | "all"required
  • periods[].fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tostring | "24:00"required

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tenthsCentsintegerrequired

    0–10000.

  • exportTenthsCentsinteger

    0–10000.

  • supplyCentsPerDayinteger

    0–10000.

  • supplyShareboolean

    Default false.

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

Errors

  • 400Not a tariff id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X PUT 'https://api.cactive.com.au/v1/me/vehicles/tariffs/{tariffId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": "flat"
  }'
Send it from this page with your session or a key.

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
}
DELETE/v1/me/vehicles/tariffs/:tariffId

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • tariffId

    A tariff's id (vtf_…).

Errors

  • 400Not a tariff id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/tariffs/{tariffId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/geofences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  geofences: {
    fenceId: string
    name?: string
    shape: {
      type: "circle"
      lat: number
      lon: number
      radiusM: number
    } | {
      type: "polygon"
      points: number[][]
    }
    enabled: boolean
    notifyOn: "leave" | "both" | "enter"
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • nameany JSONrequired
  • shapeobject | objectrequired
  • enabledboolean

    Default true.

  • notifyOn"enter" | "leave" | "both"

    Default "both".

Errors

  • 400A fence can't cross the antimeridian.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/geofences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "shape": {}
  }'
Send it from this page with your session or a key.

Response 201

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

Changes the fields given on a geofence.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • fenceId

    A geofence's id (vfn_…).

Request body

  • nameany JSON
  • shapeobject | object
  • enabledboolean
  • notifyOn"enter" | "leave" | "both"

Also checked: Say what to change.

Errors

  • 400Not a geofence id.
  • 400A fence can't cross the antimeridian.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Geofence not found
curl -X PATCH 'https://api.cactive.com.au/v1/me/vehicles/geofences/{fenceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "shape": {},
    "enabled": true
  }'
Send it from this page with your session or a key.

Response 200

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

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • fenceId

    A geofence's id (vfn_…).

Errors

  • 400Not a geofence id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Geofence not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/geofences/{fenceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/me/vehicles/automations/runs

The space's runs of its automations, newest first: each car's, with what each action did or why it didn't (180 days). One automation's with automationId.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Query parameters

  • automationIdstring
  • limitinteger

    1–200. Coerced from a string.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/automations/runs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  runs: {
    automationId: string
    vehicleId: string
    at?: string
    trigger: string
    outcome: "skipped" | "failed" | "ran"
    reason: null | string
    actions: {
      type: "command" | "notify"
      command: null | string
      outcome: "done" | "failed" | "sent" | "refused"
      reason: null | string
    }[]
  }[]
}
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 (docs/vehicles/space-automations.md).

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/me/vehicles/automations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  automations: {
    [key: string]: unknown
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Request body

  • nameany JSONrequired
  • enabledbooleanrequired
  • vehicleIdsstring[]required

    1–50 items.

  • triggerobject | object | object | object | object | object | object | object | object | objectrequired
  • conditionsobjectrequired
  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean
  • actions(object | object)[]required

    1–5 items.

  • enabledany JSON

    Default true.

  • conditionsobject

    Default {}.

  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean

Errors

  • 400"…" isn't a command.
  • 400…: …
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Vehicle not found
  • 404Geofence not found
  • 404Place not found
curl -X POST 'https://api.cactive.com.au/v1/me/vehicles/automations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "enabled": true,
    "vehicleIds": [
      "example"
    ],
    "trigger": {},
    "conditions": {
      "insidePlaceId": "<insidePlaceId>",
      "window": {
        "from": "example",
        "to": "example",
        "zone": "example"
      },
      "socMin": 1
    },
    "actions": [
      {}
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  [key: string]: unknown
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • automationId

    An automation's id (vau_…).

Request body

  • nameany JSON
  • enabledany JSON
  • vehicleIdsany JSON
  • triggerobject | object | object | object | object | object | object | object | object | object
  • conditionsobject
  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean
  • actionsany JSON

Also checked: Say what to change.

Errors

  • 400Not a automation id.
  • 400"…" isn't a command.
  • 400…: …
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Automation not found
  • 404Vehicle not found
  • 404Geofence not found
  • 404Place not found
curl -X PATCH 'https://api.cactive.com.au/v1/me/vehicles/automations/{automationId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "enabled": {},
    "vehicleIds": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  [key: string]: unknown
}
DELETE/v1/me/vehicles/automations/:automationId

Removes an automation. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • automationId

    An automation's id (vau_…).

Errors

  • 400Not a automation id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Automation not found
curl -X DELETE 'https://api.cactive.com.au/v1/me/vehicles/automations/{automationId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/vehicles/requestable

An org's cars by id and name, for its active, non-guest members to ask for; nothing else about them.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/requestable' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    vehicleId: string
    name: string
  }[]
}
GET/v1/orgs/:orgId/vehicles/sentry-force

Forced Sentry Mode on each of the space's cars: which are forced, and their floors.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    vehicleId: string
    name: string
    force: null | {
      since: number
      by: string
      floorPct: number
      pausedLowAt: null | number
      lastAt: null | number
      failedAt: null | number
    }
  }[]
}
PUT/v1/orgs/:orgId/vehicles/sentry-force

Forces Sentry Mode on for every car of the space, each turned on now (queued).

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • floorPctinteger

    Default 20. 5–80.

Also checked: Unknown fields are rejected.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "floorPct": 20
  }'
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}
DELETE/v1/orgs/:orgId/vehicles/sentry-force

Lifts forced Sentry Mode on every car of the space. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • returnTostring

    Up to 300 characters.

  • client"phone"
  • reconnectstring

    Up to 80 characters.

  • consentobjectrequired
  • consent.categories("vehicle_state" | "commands" | "charging")[]required
  • consent.locationbooleanrequired

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections/tesla/authorize' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "consent": {
      "categories": [
        "vehicle_state"
      ],
      "location": true
    }
  }'
Send it from this page with your session or a key.

Response 200

{
  url: string
  browserValue: string
  expiresAt: number
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • ticketstringrequired

    1–200 characters.

  • browserValuestringrequired

    1–200 characters.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections/tesla/finish' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": "example",
    "browserValue": "example"
  }'
Send it from this page with your session or a key.

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
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 403Connect a Tesla account in the Vehicles app.
  • 404Not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections/{connectionId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  consentUrl: string
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:read (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicles: {
    [key: string]: unknown
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 400Not a connection id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections/{connectionId}/vehicles' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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"
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectionId

    A Tesla connection's id (vconn_…); under vehicles the connection to end, rediscover or list the cars of.

Errors

  • 400Not a connection id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Connection not found
  • 409Reconnect this Tesla account first.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/connections/{connectionId}/sync' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  queued: true
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • connectionIdstringrequired
  • vinstringrequired

    Matches ^[A-HJ-NPR-Z0-9]{17}$. Trimmed. Uppercased.

  • namestring

    1–60 characters. Trimmed.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 409Someone else holds this car. Ask them to share it with you.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/claim' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "connectionId": "<connectionId>",
    "vin": "example"
  }'
Send it from this page with your session or a key.

Response 200

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

Response 201

{
  outcome: string
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
  ended: {
    vehicleId: string
  }
}
| {
  outcome: string
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
}
POST/v1/orgs/:orgId/vehicles/manual

Adds a car logged by hand (docs/vehicles/manual.md): any make and fuel, no Tesla connection. 201 { vehicle }; with odometerKm, its first odometer reading is logged too. The space's own (as a claim), from the app or a key; audited as vehicle.add.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • namestringrequired

    1–60 characters.

  • makestringrequired

    1–40 characters.

  • modelstring

    Up to 60 characters.

  • yearinteger
  • fuel"electric" | "petrol" | "diesel" | "hybrid" | "plugin_hybrid"required
  • platestring

    Up to 12 characters.

  • odometerKmnumber

    0–2000000.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/manual' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "make": "example",
    "fuel": "electric"
  }'
Send it from this page with your session or a key.

Response 201

{
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
}
GET/v1/orgs/:orgId/vehicles/profile

The space's units, currency, default tariff, the trim around a home place on shared routes, and the petrol car drives are compared with.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
  fuelLPer100Km: null | number
  fuelCentsPerL: null | number
}
PUT/v1/orgs/:orgId/vehicles/profile

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • units"metric" | "imperial"
  • currencystring

    Matches ^[A-Z]{3}$.

  • defaultTariffIdstringor null
  • homeTrimRadiusMintegeror null

    0–2000.

  • fuelLPer100Kmnumberor null

    1–40.

  • fuelCentsPerLintegeror null

    1–100000.

Also checked: Say what to change.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "units": "metric",
    "currency": "example",
    "defaultTariffId": "<defaultTariffId>"
  }'
Send it from this page with your session or a key.

Response 200

{
  units: "metric" | "imperial"
  currency: string
  defaultTariffId: null | string
  homeTrimRadiusM: null | number
  fuelLPer100Km: null | number
  fuelCentsPerL: null | number
}
GET/v1/orgs/:orgId/vehicles/places

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  places: {
    placeId: string
    name?: string
    kind: "other" | "home" | "work"
    lat: number
    lon: number
    radiusM: number
    tariffId: null | string
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • nameany JSONrequired
  • kindany JSON

    Default "other".

  • latnumberrequired

    -90–90.

  • lonnumberrequired

    -180–180.

  • radiusMany JSON

    Default 100.

  • tariffIdany JSON

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "lat": 1,
    "lon": 1
  }'
Send it from this page with your session or a key.

Response 201

{
  placeId: string
  name: string
  kind: "other" | "home" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}
PATCH/v1/orgs/:orgId/vehicles/places/:placeId

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • placeId

    A place's id: in Maps a saved place (plc_…), in Vehicles a space's charging place (vpl_…).

Request body

  • nameany JSON
  • kindany JSON
  • latnumber

    -90–90.

  • lonnumber

    -180–180.

  • radiusMany JSON
  • tariffIdany JSON

Also checked: Say what to change.

Errors

  • 400Not a place id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Place not found
  • 404Tariff not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/places/{placeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": {},
    "lat": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  placeId: string
  name?: string
  kind: "other" | "home" | "work"
  lat: number
  lon: number
  radiusM: number
  tariffId: null | string
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • placeId

    A place's id: in Maps a saved place (plc_…), in Vehicles a space's charging place (vpl_…).

Errors

  • 400Not a place id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Place not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/places/{placeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Query parameters

  • postcodestringrequired

    Matches ^\d{4}$.

  • retailerstringrequired

    Matches ^[a-z0-9][a-z0-9-]{1,38}$.

Errors

  • 400Not an Australian postcode.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/tariffs/plans?postcode=example&retailer=example' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

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
  }[]
}
GET/v1/orgs/:orgId/vehicles/tariffs

The space's tariffs, by name.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/tariffs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  tariffs: {
    [key: string]: unknown
    [key: number]: unknown
  }[]
}
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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • nameany JSONrequired
  • kind"flat" | "tou"required
  • flatTenthsCentsinteger

    0–10000.

  • zonestring

    Up to 64 characters.

  • periodsobject[]

    1–12 items.

  • periods[].name"peak" | "shoulder" | "offpeak"required
  • periods[].days"weekday" | "weekend" | "all"required
  • periods[].fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tostring | "24:00"required

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tenthsCentsintegerrequired

    0–10000.

  • exportTenthsCentsinteger

    0–10000.

  • supplyCentsPerDayinteger

    0–10000.

  • supplyShareboolean

    Default false.

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

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/tariffs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": "flat"
  }'
Send it from this page with your session or a key.

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
}
PUT/v1/orgs/:orgId/vehicles/tariffs/:tariffId

Replaces a tariff with the one given.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • tariffId

    A tariff's id (vtf_…).

Request body

  • nameany JSONrequired
  • kind"flat" | "tou"required
  • flatTenthsCentsinteger

    0–10000.

  • zonestring

    Up to 64 characters.

  • periodsobject[]

    1–12 items.

  • periods[].name"peak" | "shoulder" | "offpeak"required
  • periods[].days"weekday" | "weekend" | "all"required
  • periods[].fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tostring | "24:00"required

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • periods[].tenthsCentsintegerrequired

    0–10000.

  • exportTenthsCentsinteger

    0–10000.

  • supplyCentsPerDayinteger

    0–10000.

  • supplyShareboolean

    Default false.

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

Errors

  • 400Not a tariff id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/tariffs/{tariffId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "kind": "flat"
  }'
Send it from this page with your session or a key.

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
}
DELETE/v1/orgs/:orgId/vehicles/tariffs/:tariffId

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • tariffId

    A tariff's id (vtf_…).

Errors

  • 400Not a tariff id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Tariff not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/tariffs/{tariffId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/geofences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

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

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • nameany JSONrequired
  • shapeobject | objectrequired
  • enabledboolean

    Default true.

  • notifyOn"enter" | "leave" | "both"

    Default "both".

Errors

  • 400A fence can't cross the antimeridian.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/geofences' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "shape": {}
  }'
Send it from this page with your session or a key.

Response 201

{
  fenceId: string
  name: string
  shape: {
    type: "circle"
    lat: number
    lon: number
    radiusM: number
  } | {
    type: "polygon"
    points: number[][]
  }
  enabled: boolean
  notifyOn: "leave" | "both" | "enter"
}
PATCH/v1/orgs/:orgId/vehicles/geofences/:fenceId

Changes the fields given on a geofence.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • fenceId

    A geofence's id (vfn_…).

Request body

  • nameany JSON
  • shapeobject | object
  • enabledboolean
  • notifyOn"enter" | "leave" | "both"

Also checked: Say what to change.

Errors

  • 400Not a geofence id.
  • 400A fence can't cross the antimeridian.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Geofence not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/geofences/{fenceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "shape": {},
    "enabled": true
  }'
Send it from this page with your session or a key.

Response 200

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

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

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • fenceId

    A geofence's id (vfn_…).

Errors

  • 400Not a geofence id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Geofence not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/geofences/{fenceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/orgs/:orgId/vehicles/automations/runs

The space's runs of its automations, newest first: each car's, with what each action did or why it didn't (180 days). One automation's with automationId.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Query parameters

  • automationIdstring
  • limitinteger

    1–200. Coerced from a string.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/automations/runs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  runs: {
    automationId: string
    vehicleId: string
    at?: string
    trigger: string
    outcome: "skipped" | "failed" | "ran"
    reason: null | string
    actions: {
      type: "command" | "notify"
      command: null | string
      outcome: "done" | "failed" | "sent" | "refused"
      reason: null | string
    }[]
  }[]
}
GET/v1/orgs/:orgId/vehicles/automations

The space's automations: a trigger, conditions and up to five actions on the cars named, run with the creator's capabilities (docs/vehicles/space-automations.md).

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:read (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:read on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/automations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  automations: {
    [key: string]: unknown
  }[]
}
POST/v1/orgs/:orgId/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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • nameany JSONrequired
  • enabledbooleanrequired
  • vehicleIdsstring[]required

    1–50 items.

  • triggerobject | object | object | object | object | object | object | object | object | objectrequired
  • conditionsobjectrequired
  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean
  • actions(object | object)[]required

    1–5 items.

  • enabledany JSON

    Default true.

  • conditionsobject

    Default {}.

  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean

Errors

  • 400"…" isn't a command.
  • 400…: …
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Vehicle not found
  • 404Geofence not found
  • 404Place not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/automations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "enabled": true,
    "vehicleIds": [
      "example"
    ],
    "trigger": {},
    "conditions": {
      "insidePlaceId": "<insidePlaceId>",
      "window": {
        "from": "example",
        "to": "example",
        "zone": "example"
      },
      "socMin": 1
    },
    "actions": [
      {}
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  [key: string]: unknown
}
PATCH/v1/orgs/:orgId/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
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • automationId

    An automation's id (vau_…).

Request body

  • nameany JSON
  • enabledany JSON
  • vehicleIdsany JSON
  • triggerobject | object | object | object | object | object | object | object | object | object
  • conditionsobject
  • conditions.insidePlaceIdstring
  • conditions.windowobject
  • conditions.window.fromstringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.tostringrequired

    Matches ^([01]\d|2[0-3]):[0-5]\d$.

  • conditions.window.zonestringrequired

    Up to 64 characters.

  • conditions.socMininteger

    0–100.

  • conditions.socMaxinteger

    0–100.

  • conditions.pluggedboolean
  • conditions.nobodyInsideboolean
  • actionsany JSON

Also checked: Say what to change.

Errors

  • 400Not a automation id.
  • 400"…" isn't a command.
  • 400…: …
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Automation not found
  • 404Vehicle not found
  • 404Geofence not found
  • 404Place not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/automations/{automationId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {},
    "enabled": {},
    "vehicleIds": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  [key: string]: unknown
}
DELETE/v1/orgs/:orgId/vehicles/automations/:automationId

Removes an automation. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
vehicles:admin (when orgId), vehicles:write (when actor.type === "user")
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • automationId

    An automation's id (vau_…).

Errors

  • 400Not a automation id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 403Its owner hasn't let API keys use their Personal Vehicles (Vehicles → Privacy).
  • 403Vehicles needs vehicles:write on a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
  • 404Automation not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/vehicles/automations/{automationId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/access-links/:token

What a request link opens: the car's name and its owner's, nothing else. 404 for anything that isn't a live link.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/access-links/{token}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicle: {
    name: string
  }
  owner: {
    kind: string
    name: null | string
    you: boolean
  }
  request: null | {
    vehicleId: string
    userId: string
    status: "pending" | "approved" | "declined" | "withdrawn" | "lapsed"
    terms: {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
          from: string
          to: string
          dates?: string[]
        }[]
      }
    }
    categories: string[]
    reason: null | string
    via: "org" | "link"
    createdAt: string
    lapsesAt: number
    decidedAt: null | string
    given: null | {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
          from: string
          to: string
          dates?: string[]
        }[]
      }
    }
    note: null | string
  }
}
GET/v1/vehicles/access-requests

The person's own requests, and those for the cars they hold through a space (their own, and orgs where they're a fleet admin).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/access-requests' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  mine: {
    vehicleName: string
    ownerName: null | string
    vehicleId: string
    userId: string
    status: "pending" | "approved" | "declined" | "withdrawn" | "lapsed"
    terms: {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    categories: string[]
    reason: null | string
    via: "org" | "link"
    createdAt: string
    lapsesAt: number
    decidedAt: null | string
    given: null | {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    note: null | string
  }[]
  incoming: {
    vehicleName: string
    spaceId: string
    askerName: null | string
    vehicleId: string
    userId: string
    status: "pending" | "approved" | "declined" | "withdrawn" | "lapsed"
    terms: {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    categories: string[]
    reason: null | string
    via: "org" | "link"
    createdAt: string
    lapsesAt: number
    decidedAt: null | string
    given: null | {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    note: null | string
  }[]
}
POST/v1/vehicles/access-requests

Asks for access: through a link's token, or a vehicleId of the org the person is an active, non-guest member of. 201 with the request; 404 for a car they can't reach this way, 409 exists or holds, 429 with Retry-After.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • tokenstring

    Up to 64 characters.

  • vehicleIdstring

    Up to 64 characters.

  • capabilitiesstring[]required

    1–32 items. Each up to 32 characters.

  • paramsobject

    Keys up to 32 characters. Values: string (up to 64 characters), number or boolean.

  • notBeforeinteger

    > 0, ≤ 253402300799.

  • expiresAtinteger

    > 0, ≤ 253402300799.

  • scheduleobject
  • schedule.tzstringrequired

    1–64 characters.

  • schedule.windows(object | object)[]required

    1–8 items.

  • reasonstring

    Up to 2,000 characters.

Also checked: Unknown fields are rejected. Give the link's token or the car's id.

Errors

  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/access-requests' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "capabilities": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  request: {
    vehicleName: string
    vehicleId: string
    userId: string
    status: "pending" | "approved" | "declined" | "withdrawn" | "lapsed"
    terms: {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
          from: string
          to: string
          dates?: string[]
        }[]
      }
    }
    categories: string[]
    reason: null | string
    via: "org" | "link"
    createdAt: string
    lapsesAt: number
    decidedAt: null | string
    given: null | {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
          from: string
          to: string
          dates?: string[]
        }[]
      }
    }
    note: null | string
  }
}
DELETE/v1/vehicles/access-requests/:vehicleId

Withdraws the person's own open request for a car. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Asking for and answering access is done by the person, in the app.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/access-requests/{vehicleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/access-requests

A car's requests, for its owner and an org's fleet admins.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-requests' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  requests: {
    askerName: null | string
    vehicleId: string
    userId: string
    status: "pending" | "approved" | "declined" | "withdrawn" | "lapsed"
    terms: {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    categories: string[]
    reason: null | string
    via: "org" | "link"
    createdAt: string
    lapsesAt: number
    decidedAt: null | string
    given: null | {
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
    }
    note: null | string
  }[]
}
POST/v1/vehicles/:vehicleId/access-requests/:userId/approve

Approves a request, as asked or narrowed (capabilities, params, notBefore, expiresAt, schedule; null clears).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • userId

    A member's user id (usr_…).

Request body

  • capabilitiesstring[]

    1–32 items. Each up to 32 characters.

  • paramsobjector null

    Keys up to 32 characters. Values: string (up to 64 characters), number or boolean.

  • notBeforeintegeror null

    > 0, ≤ 253402300799.

  • expiresAtintegeror null

    > 0, ≤ 253402300799.

  • scheduleobjector null
  • schedule.tzstringrequired

    1–64 characters.

  • schedule.windows(object | object)[]required

    1–8 items.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400Not a person id.
  • 403Vehicles needs a key made by a person.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Name the chat's space in x-si-org: an organisation or personal.
  • 403You aren't a member of that organisation.
  • 403Sharing needs a signed-in person or an organisation's key.
  • 403Missing scope sharing:write
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-requests/{userId}/approve' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "capabilities": [
      "example"
    ],
    "params": {},
    "notBefore": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  given: {
    capabilities: string[]
    params?: {
      [key: string]: boolean | string | number
    }
    notBefore?: number
    expiresAt?: number
    schedule?: {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
  }
}
POST/v1/vehicles/:vehicleId/access-requests/:userId/decline

Declines a request, with an optional note to the asker. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • userId

    A member's user id (usr_…).

Request body

  • notestring

    Up to 300 characters.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400Not a person id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-requests/{userId}/decline' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "note": "example"
  }'
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/access-links

The car's live request links (never their tokens).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  links: {
    linkId: string
    createdAt: string
    expiresAt: number
  }[]
}
POST/v1/vehicles/:vehicleId/access-links

A new request link: its address is in this answer only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • daysinteger

    Default 7. 1–30.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "days": 7
  }'
Send it from this page with your session or a key.

Response 201

{
  link: {
    linkId: string
    createdAt: string
    expiresAt: number
  }
  url: string
}
DELETE/v1/vehicles/:vehicleId/access-links/:linkId

Ends a request link: it opens nothing from now. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • linkId

    Link id (ilk_… for issue links, irl_… for remote links, plk_… for Photos links, lnk_… for sharing links and a drive's share links: not the link's secret).

Errors

  • 400Not a vehicle id.
  • 400Not a link id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/access-links/{linkId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/sentry-force

Whether Sentry Mode is forced: its whole state for the owner, whether it is for anyone who can see the car.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  force: null | {
    since: number
    by: string
    floorPct: number
    pausedLowAt: null | number
    lastAt: null | number
    failedAt: null | number
  }
}
| {
  force: null | {
    forced: true
  }
}
PUT/v1/vehicles/:vehicleId/sentry-force

Forces Sentry Mode on for everyone (or changes the battery floor), and turns it on now.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • floorPctinteger

    Default 20. 5–80.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "floorPct": 20
  }'
Send it from this page with your session or a key.

Response 200

{
  force: null | {
    since: number
    by: string
    floorPct: number
    pausedLowAt: null | number
    lastAt: null | number
    failedAt: null | number
  }
  command: {
    status: "already"
    commandId?: undefined
    code?: undefined
    error?: undefined
  } | {
    status: "queued"
    commandId: string
    code?: undefined
    error?: undefined
  } | {
    status: "refused"
    code: string
    error: string
    commandId?: undefined
  }
}
DELETE/v1/vehicles/:vehicleId/sentry-force

Lifts forced Sentry Mode: anyone who may change the car's settings can turn it off again. 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/sentry-force' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/speed-limit

A shared drive's Speed Limit Mode session, for the owner: the limit, whose drive, and whether it is being turned off (docs/vehicles/sharing.md → Speed Limit Mode sessions).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/speed-limit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  session: null | {
    sessionId: string
    limitKmh: number
    startedAt: number
    lastOnAt: number
    phase: "on" | "parked" | "releasing"
    holders: {
      userId: string
      name: null | string
      limitKmh: number
      at: number
    }[]
    wasOn: boolean | null
    ending: null | {
      reason: "owner" | "revoked" | "expired" | "stale" | "changed" | "drive_ended"
      at: number
    }
    release: null | {
      tries: number
      tryAt: null | number
      nextAt: null | number
      code: null | string
    }
  }
}
DELETE/v1/vehicles/:vehicleId/speed-limit

The owner ends a session: Speed Limit Mode is turned off at the next park, never mid-drive. 404 when none is open.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/speed-limit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  session: null | {
    sessionId: string
    limitKmh: number
    startedAt: number
    lastOnAt: number
    phase: "on" | "parked" | "releasing"
    holders: {
      userId: string
      name: null | string
      limitKmh: number
      at: number
    }[]
    wasOn: boolean | null
    ending: null | {
      reason: "owner" | "revoked" | "expired" | "stale" | "changed" | "drive_ended"
      at: number
    }
    release: null | {
      tries: number
      tryAt: null | number
      nextAt: null | number
      code: null | string
    }
  }
}
GET/v1/vehicles/:vehicleId

META and LIVE with the caller's capabilities, telemetry health and key status. The position only with location.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  restorableUntil?: string
  ended?: {
    at?: string
    reason?: "removed" | "archived" | "access_lost" | "new_owner" | "ownership_changed"
  }
  loggedOdometer?: {
    km: number
    at?: string
  }
  provider?: "manual"
  make?: string
  year?: number
  fuel?: "electric" | "petrol" | "diesel" | "hybrid" | "plugin_hybrid"
  pictureMode?: "tesla" | "drawing"
  vehicleId: string
  name: string
  model?: string
  trim?: string
  capabilities: string[]
  health?: {
    streamError?: {
      persists?: boolean
      resent?: boolean
      kind: "other" | "config" | "certificate" | "unreachable"
      since: string
    }
    gone?: {
      at: string
      reason: "revoked" | "disconnected"
    }
    key: string
    connection: string
    checkedAt?: string
    profile?: "standard" | "economy"
    telemetry: "error" | "pending" | "off" | "configured" | "streaming" | "waiting_for_key" | "firmware_too_old" | "limit_reached" | "unsupported" | "suspended" | "unsigned"
    telemetryLabel: string
    polling: boolean
  }
  loggingResumeAt?: string
  loggingPausedAt?: string
  privacy?: {
    pausedUntil?: number
    locationPrecision?: "hidden" | "exact" | "approximate"
    drivingState?: "hidden" | "shown"
    speedLive?: "hidden" | "shown"
    speedDrives?: "hidden" | "shown"
    placeNames?: "hidden" | "shown"
    music?: "hidden" | "shown"
    tripsVisible?: "none" | "all"
    chargesVisible?: "none" | "all"
  }
  places?: {
    home?: boolean
    work?: boolean
    favorite?: boolean
  }
  navigation?: {
    [key: string]: unknown
  }
  position?: {
    [key: string]: unknown
  }
  tyres?: {
    kpa?: number[]
    warnings?: {
      fl?: "hard" | "soft"
      fr?: "hard" | "soft"
      rl?: "hard" | "soft"
      rr?: "hard" | "soft"
    }
  }
  software?: {
    update?: null | {
      status: "scheduled" | "available" | "downloading" | "installing"
      version: string
      minutes?: number
      percent?: number
    }
    version?: string
  }
  gear?: "N" | "D" | "R" | "P"
  speedKmh?: number
  odometerKm?: number
  tripMeterKm?: number
  sentryForced?: boolean
  config?: {
    exteriorColor?: string
    roofColor?: string
    wheelType?: string
    rightHand?: boolean
  }
  climate?: {
    settings?: {
      ac?: boolean
      auto?: boolean
      seatHeat?: {
        [key: string]: number
      }
      seatAuto?: {
        [key: string]: boolean
      }
      seatCool?: {
        [key: string]: number
      }
      wheelHeat?: number
      wheelHeatAuto?: boolean
      defrost?: string
      rearDefrost?: boolean
      keeper?: string
      overheat?: string
      overheatLimit?: string
    }
    setpoint?: {
      driverC?: number
      passengerC?: number
    }
    on?: boolean
    insideC?: number
    outsideC?: number
  }
  sentry?: boolean
  security?: {
    pinToDrive?: boolean
    keylessDriving?: boolean
    keys?: number
    serviceMode?: boolean
  }
  state?: "offline" | "charging" | "online" | "parked" | "driving" | "asleep"
  lastSeen?: string
  battery?: {
    lifetimeKwh?: number
    heater?: {
      on?: boolean
      short?: boolean
    }
    soc?: number
    rangeKm?: number
    estRangeKm?: number
    cells?: {
      tempMinC?: number
      tempMaxC?: number
      voltMin?: number
      voltMax?: number
    }
  }
  charge?: {
    schedule?: {
      mode?: string
      start?: string
      pending?: boolean
      preconditioning?: boolean
    }
    plugged?: boolean
    portOpen?: boolean
    kw?: number
    limit?: number
    etaMin?: number
    amps?: number
    volts?: number
    charger?: {
      ampsSet?: number
      ampsMax?: number
      phases?: number
      cable?: string
      latch?: string
      port?: string
    }
  }
  modes?: {
    valet?: boolean
    guest?: boolean
    speedLimit?: boolean
    speedLimitKmh?: number
  }
  locks?: {
    locked?: boolean
    doorsOpen?: string[]
    windowsOpen?: string[]
    trunk?: "open" | "closed"
    frunk?: "open" | "closed"
    powerLiftgate?: boolean
    hazards?: boolean
  }
  colour?: string
  art?: string
  picture?: {
    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?: true
    source: "photo" | "tesla" | "appearance"
  }
}
POST/v1/vehicles/:vehicleId/watch

Renews the live lease (open apps send it every 30 s while the car is on screen). 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/watch' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/key

Pairing status, the pairing link and what to do next; opening it restarts the key checks when they have lapsed.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/key' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  checkedAt?: string
  status: "pending" | "lost" | "paired" | "unpaired" | "not_required"
  required: boolean
  link?: string
  requirements: ("tesla_app_same_account" | "car_online")[]
  keyCount?: number
  keysFull: boolean
  keyListUrl?: string
  firmware?: string
  pollMs?: number
  vehicleId: string
}
GET/v1/vehicles/:vehicleId/trips

Drives, newest first. class, tag, driver, min (km) filter; cursor resumes across months.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromstring

    Up to 40 characters.

  • tostring

    Up to 40 characters.

  • cursorstring

    Up to 700 characters.

  • limitinteger

    1–100. Coerced from a string.

  • class"business" | "personal" | "commute" | "private"
  • tagstring

    1–40 characters. Trimmed.

  • excludeTag"0" | "1"
  • driverstring

    Up to 60 characters.

  • minnumber

    0–100000. Coerced from a string.

  • startPlacestring

    1–60 characters. Trimmed.

  • endPlacestring

    1–60 characters. Trimmed.

  • excludeStart"0" | "1"
  • excludeEnd"0" | "1"
  • nearstring

    Matches ^-?\d{1,2}(\.\d{1,7})?,-?\d{1,3}(\.\d{1,7})?(,\d{2,5})?$.

Errors

  • 400Not a vehicle id.
  • 400near: not a position.
  • 400near: 50 to 50,000 metres.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  next?: string
  trips: {
    hasTrack: boolean
    path?: {
      lat: number
      lon: number
    }[]
    privacy?: {
      hiddenFrom: string[]
      speedHiddenFrom: string[]
    }
    endsHidden?: true
    startPlace?: string
    endPlace?: string
    secondsOver?: {
      [key: string]: number
    }
    kmOver?: {
      [key: string]: number
    }
    score?: number
    harshAccel?: number
    harshBraking?: number
    harshCornering?: number
    style?: {
      pedalS?: number
      pedalAvgPct?: number
      heavyS?: number
      brakes?: number
      cruiseS?: number
      score?: number
    }
    weather?: string
    mine: boolean
    notes?: null | string
    startOdometerKm?: number
    endOdometerKm?: number
    manual?: true
    imported?: true
    assistedKm?: number
    class?: "private" | "personal" | "business" | "commute"
    purpose?: string
    tags?: string[]
    driverId?: string
    outsideCMin?: number
    outsideCMax?: number
    elevationGainM?: number
    elevationLossM?: number
    maxSpeedKmh?: number
    avgMovingSpeedKmh?: number
    tripId: string
    startedAt?: string
    endedAt?: string
    distanceKm?: number
    energyKwh?: number
    whPerKm?: number
    socFrom?: number
    socTo?: number
    placesHidden?: boolean
    speedHidden?: boolean
  }[]
}
GET/v1/vehicles/:vehicleId/trips/current

The drive still open, as far as the car has gone: its points after since, for the app that draws it while it goes (it asks every 5 s, and only for what is new). Needs trips and location (shown always: a grant that shows the position only while the holder drives never does, as in the detail), and a grant whose trips filter shows the open drive, which has no class or driver yet: only every drive, with no class tag. Without one, or without a drive open, the answer is the same open: false.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • sincestring

    Up to 40 characters.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/current' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  open: false
  points: []
}
| {
  truncated?: true
  through?: number
  open: true
  tripId: string
  startedAt?: string
  points: {
    headingDeg: number
    soc: number
    powerKw: number
    elevM?: number
    insideC?: number
    outsideC?: number
    ratedRangeKm?: number
    speedKmh?: number
    limitKmh?: number
    t: number
    lat: number
    lon: number
  }[]
}
POST/v1/vehicles/:vehicleId/trips/roads

Drives' lines on the roads they took (docs/maps/timeline.md → Roads), for the drive page and the drives map: { tripIds } (up to 50) answers { roads: { [tripId]: stretches | "pending" | null } }, kept lines and a few new matchings each time (pending: ask again shortly). Drives the caller doesn't see are left out. Display only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • tripIdsstring[]required

    1–50 items.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/roads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "tripIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  roads: {
    [key: string]: null | "pending" | {
      road: boolean
      points: [number, number][]
      from: number
      to: number
      t?: [number, number]
    }[]
  }
}
GET/v1/vehicles/:vehicleId/trips/:tripId

A drive: the summary, and its thumbnail path when it has no track (an imported route). ?points=1 adds the decoded track (the server opens it), after since when given.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Query parameters

  • points"0" | "1"
  • sincestring

    Up to 40 characters.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  music?: {
    plays: {
      atS: number
      listenedS: number
      title?: string
      artist?: string
      album?: string
      station?: string
      source?: string
    }[]
  }
  trip: {
    hasTrack: boolean
    path?: {
      lat: number
      lon: number
    }[]
    privacy?: {
      hiddenFrom: string[]
      speedHiddenFrom: string[]
    }
    endsHidden?: true
    startPlace?: string
    endPlace?: string
    secondsOver?: {
      [key: string]: number
    }
    kmOver?: {
      [key: string]: number
    }
    score?: number
    harshAccel?: number
    harshBraking?: number
    harshCornering?: number
    style?: {
      pedalS?: number
      pedalAvgPct?: number
      heavyS?: number
      brakes?: number
      cruiseS?: number
      score?: number
    }
    weather?: string
    mine: boolean
    notes?: null | string
    startOdometerKm?: number
    endOdometerKm?: number
    manual?: true
    imported?: true
    assistedKm?: number
    class?: "private" | "personal" | "business" | "commute"
    purpose?: string
    tags?: string[]
    driverId?: string
    outsideCMin?: number
    outsideCMax?: number
    elevationGainM?: number
    elevationLossM?: number
    maxSpeedKmh?: number
    avgMovingSpeedKmh?: number
    tripId: string
    startedAt?: string
    endedAt?: string
    distanceKm?: number
    energyKwh?: number
    whPerKm?: number
    socFrom?: number
    socTo?: number
    placesHidden?: boolean
    speedHidden?: boolean
  }
  events: {
    eventId: string
    kind: string
    at?: string
    severity?: string
    values?: {
      [key: string]: boolean | number
    }
  }[]
  track: {
    available: boolean
    count?: number
    points?: {
      [key: string]: undefined | number
    }[]
  }
}
GET/v1/vehicles/:vehicleId/stats/today

Today's drives: the distance and energy, and the count for those who see every drive, as totals and nothing finer. The day is cut in the zone asked for (?tz=, a place's IANA name) for those who see every drive, else in the car's space's. view is enough for the distance and energy, whatever the grant's trip filters hide, because a sum names no drive, time or place (docs/vehicles/api.md → Today's totals).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • tzstring

    1–64 characters. Trimmed.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/stats/today' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  drives?: number
  assistedKm: number
  assistedOfKm?: number
  day: string
  timeZone: string
  from?: string
  to?: string
  distanceKm: number
  energyKwh: number
} | {
  drives?: number
  assistedKm?: undefined
  assistedOfKm?: undefined
  day: string
  timeZone: string
  from?: string
  to?: string
  distanceKm: number
  energyKwh: number
}
GET/v1/vehicles/:vehicleId/charges

Charging sessions: with trips, the places; with costs, what they cost. Either opens the list.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromstring

    Up to 40 characters.

  • tostring

    Up to 40 characters.

  • cursorstring

    Up to 700 characters.

  • limitinteger

    1–100. Coerced from a string.

  • placestring

    1–60 characters. Trimmed.

  • excludePlace"0" | "1"
  • supercharger"0" | "1"
  • minKwhnumber

    0–1000. Coerced from a string.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/charges' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  next?: string
  charges: {
    notes?: null | string
    odometerKm?: number
    litres?: number
    manual?: true
    privacy?: {
      hiddenFrom: string[]
    }
    place?: string
    costCents?: number
    costSource?: string
    tariffId?: string
    chargeId: string
    startedAt?: string
    endedAt?: string
    kind?: "other" | "home" | "work" | "supercharger"
    kwhAdded?: number
    kwhDrawn?: number
    socFrom?: number
    socTo?: number
    maxKw?: number
    maxAmps?: number
    volts?: number
    phases?: number
    cable?: "iec" | "sae" | "gb_ac" | "gb_dc"
    cellTempMinC?: number
    cellTempMaxC?: number
    heatedS?: number
  }[]
}
GET/v1/vehicles/:vehicleId/idles

Parked periods (battery lost while parked, with Sentry and climate shares).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromstring

    Up to 40 characters.

  • tostring

    Up to 40 characters.

  • cursorstring

    Up to 700 characters.

  • limitinteger

    1–100. Coerced from a string.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/idles' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  idles: []
  hidden: true
}
| {
  next?: string
  idles: {
    place?: string
    spans?: {
      [key: string]: ((undefined | string)[])[]
    }
    climateFraction?: number
    asleepFraction?: number
    sentryFraction?: number
    idleId: string
    startedAt?: string
    endedAt?: string
    socLostPct?: number
    kwhLost?: number
  }[]
}
POST/v1/vehicles/:vehicleId/commands/:commandName

Sends a command through K2's command service (docs/vehicles/commands.md → The service): the capability each needs, its arguments, the grant's terms, the confirmation (a nonce for a hold, the token's step-up), the limits and the queue are the service's, from commandDef. Idempotency-Key is required and makes a repeat return the first result. 200 { commandId, status: "succeeded" }, 202 { commandId, status, approvalId } while it is queued or waits for approval, and the service's refusals with their status and code: 409 confirm (with a nonce), 403 terms, step_up, approval_required, 409 boot_open (a lock while the boot or front trunk is open) and no_update (a software update the car hasn't got ready), 424 vehicle (with Tesla's reason), 429 (Retry-After), 422 bad_args and unsupported (Close Trunk on a boot that closes by hand).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • commandName

    A command's name, such as lock, climate_on or charge_limit; its capability decides who may send it.

Request body

  • argsobject

    Keys up to 40 characters. Values: any JSON.

  • noncestring

    1–100 characters.

  • fixobject
  • fix.latnumberrequired

    -90–90.

  • fix.lonnumberrequired

    -180–180.

  • fix.fixAtintegerrequired

    0–8640000000000000.

Errors

  • 400Send an Idempotency-Key header, so a repeated request returns the first result.
  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Unknown command.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/commands/{commandName}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "args": {},
    "nonce": "example",
    "fix": {
      "lat": 1,
      "lon": 1,
      "fixAt": 1
    }
  }'
Send it from this page with your session or a key.
GET/v1/vehicles/:vehicleId/commands/:commandId

A command's state: your own, or anyone's with share.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • commandId

    A command's id (cmd_…), as sending it returned it.

Errors

  • 400Not a vehicle id.
  • 400Not a command id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/commands/{commandId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  at?: string
  approvalId: null | string
  reason?: string
  commandId: string
  command: string
  status: "unknown" | "queued" | "failed" | "sent" | "succeeded" | "needs_approval" | "waking"
}
DELETE/v1/vehicles/:vehicleId

/** Removes a car with a 7-day undo. For a period that ended some other way (sold, access lost), ?history=delete deletes its history for good.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • history"delete"

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  removedAt?: string
  restorableUntil?: string
}
| {
  vehicleId: string
  historyDeletion: string
}
POST/v1/vehicles/:vehicleId/archive

Archives the car (docs/vehicles/tesla.md → Registry): its period ends, nothing more is recorded and its shares end, and its key and history stay for the owner to read (no purge). The owner's alone; 409 for a period already ended. restore undoes it.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/archive' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  archivedAt?: string
}
PUT/v1/vehicles/:vehicleId/logging

Pauses or resumes the car's data logging ({ paused }; docs/vehicles/settings.md → Paused logging): paused, nothing is recorded and our telemetry config comes off the car; commands still work. The owner's alone; 409 for a period that has ended. Audited in an organisation's log (vehicle.settings_update, change logging).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • pausedbooleanrequired
  • untilinteger

    > 0.

Errors

  • 400Not a vehicle id.
  • 400A pause ends an hour to a year from now.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/logging' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "paused": true
  }'
Send it from this page with your session or a key.

Response 200

{
  resumeAt?: string
  pausedAt?: string
  paused: boolean
}
POST/v1/vehicles/:vehicleId/restore

Undoes a removal within 7 days, or an archive (the connection must still list the car and the VIN be free).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/restore' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicle: {
    provider?: "manual"
    accessType?: "OWNER" | "DRIVER"
    keyStatus: "pending" | "lost" | "paired" | "unpaired" | "not_required"
    periodStart?: string
    vinTail?: string
    vehicleId: string
    model?: string
    trim?: string
  }
}
PUT/v1/vehicles/:vehicleId/settings

The car's settings: its name (1 to 60 characters, no control or invisible formatting characters) and its picture, Tesla's or our drawing (pictureMode on both rows; docs/vehicles/pictures.md). Audited as vehicle.settings_update with the change, never the value.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • namestring

    Up to 200 characters.

  • picture"tesla" | "drawing"

Also checked: Send a name or a picture.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "picture": "tesla"
  }'
Send it from this page with your session or a key.

Response 200

{
  pictureMode?: "tesla" | "drawing"
  name?: string
  vehicleId: string
}
POST/v1/vehicles/:vehicleId/picture

Reads the car's configuration again and resolves its picture (the owner's Refresh picture): 202, queued for the worker, which alone reads Tesla and only when the car is online. 429 with Retry-After within a day of the last read, 409 for a finished period.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/picture' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  lastReadAt?: string
  queued: true
}
GET/v1/vehicles/:vehicleId/events

What happened to the car, newest first: alerts and the car being moved while parked, and with the drives' events (speeding, harsh braking) for those who see every drive and hold behaviour. kind narrows it. An event the caller may not see is left out as if it were not there, and so is an alert raised while the car was in a drive they do not see (its time would place that drive); next is sealed.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromstring

    Up to 40 characters.

  • tostring

    Up to 40 characters.

  • cursorstring

    Up to 700 characters.

  • limitinteger

    1–100. Coerced from a string.

  • kindstring

    1–60 characters. Matches ^[A-Za-z0-9_.:-]+$. Trimmed.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/events' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  next?: string
  events: {
    tripId?: string
    eventId: string
    kind: string
    at?: string
    severity?: "warning" | "critical" | "info"
    values?: {
      [key: string]: boolean | number
    }
  }[]
}
GET/v1/vehicles/:vehicleId/battery

The battery now, and its capacity over time as the charges give it: each charge that took the state of charge up by 20 points or more says what the battery holds (kWh added over the points gained), and a month's figure is the median. Beside them, the months measured while parked (measured, the cap# rows an import or the stream wrote), which win where both exist. Once the months span half a year, what the pack has kept is the median of the last three over the best of the first three (retainedPct, baselineKwh, baselineMonth). Battery Health (docs/vehicles/insights-battery.md → Battery health): health is the latest capacity over the pack's capacity new (the owner's originalKwh, else the best of the first months), with the warranty's terms (limit rows) and when its years end (from the owner's pack date, else the car's history). For a caller who may see charges, readings: each charge that added 5 kWh or more, what the pack held and its rated range at 100%, and the cycles so far; the odometer at each only for a caller who sees every drive (with it, the distance between charges). lifetime: the car's lifetime energy by month, where months measured it.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 730 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/battery?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated?: true
  lifetime: {
    month: string
    kwh: number
  }[]
  from?: string
  to?: string
  cycles?: {
    points: {
      at?: string
      cycles: number
      odometerKm?: number
    }[]
    estimated?: {
      odometerKm: number
      cycles: number
    }
  }
  readings?: {
    odometerKm?: number
    rangeKm?: number
    at?: string
    kwh: number
  }[]
  health?: {
    originalKwh: number
    originalFrom: string
    pct: number
  }
  pack: {
    originalKwh?: number
    date?: string
  }
  warranty: {
    kmLeft?: number
    retentionPct: number
    years: number
    km: number
    endsOn: string
    from: string
  }
  now: {
    plugged?: boolean
    chargeLimitPct?: number
    chargeKw?: number
    odometerKm?: number
    soc?: number
    rangeKm?: number
    estRangeKm?: number
  }
  capacity: {
    lifetimeCycles?: number
    cycles?: number
    latestKwh?: number
    baselineKwh: number
    baselineMonth: string
    retainedPct: number
    method: string
    unit: string
    months: {
      charges?: number
      month: string
      kwh: number
    }[]
    measured: {
      month: string
      kwh: number
      source: "stream" | "import"
    }[]
  } | {
    lifetimeCycles?: number
    cycles?: number
    latestKwh?: number
    baselineKwh?: undefined
    baselineMonth?: undefined
    retainedPct?: undefined
    method: string
    unit: string
    months: {
      charges?: number
      month: string
      kwh: number
    }[]
    measured: {
      month: string
      kwh: number
      source: "stream" | "import"
    }[]
  }
}
GET/v1/vehicles/:vehicleId/tyres

The four tyre pressures as the car last reported them (kPa), the tyre alerts of the last 90 days (left out when raised during a drive the caller does not see, as in the events), and the days in a range (at most two years, the default): each wheel's lowest, highest and cold reading a local day (tyre# rows, streamed or imported). A day's highest says the car was driven, so the days go only to a caller who sees every drive; anyone else gets history: "hidden".

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 730 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/tyres?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  days?: {
    day: string
  }[]
  warnings: {
    eventId: string
    kind: string
    at?: string
    ongoing: boolean
  }[]
  warnedNow?: {
    fl?: "hard" | "soft"
    fr?: "hard" | "soft"
    rl?: "hard" | "soft"
    rr?: "hard" | "soft"
  }
  reportedAt?: string
  kpa?: {
    fl?: number
    fr?: number
    rl?: number
    rr?: number
  }
  history?: string
}
GET/v1/vehicles/:vehicleId/efficiency

Wh/km by outside temperature and speed, from the drives the caller sees (so a holder of some drives gets their own picture, and the count says how many that was): each cell is the distance-weighted average of the drives in that 5 °C and 20 km/h band, with the distance and drives in it. The real-world range is the battery's estimated capacity at the state of charge over the average. There is no model of what a drive should have used, nor climate, wind or tyre effects, yet.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 730 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/efficiency?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated?: true
  method: string
  realWorldRangeKm?: number
  habits?: {
    coldStart?: {
      cold: {
        km: number
        whPerKm: number
        drives: number
      }
      warm: {
        km: number
        whPerKm: number
        drives: number
      }
    }
    preconditioned?: {
      yes: {
        km: number
        whPerKm: number
        drives: number
      }
      no: {
        km: number
        whPerKm: number
        drives: number
      }
    }
    harsh?: {
      hard: {
        km: number
        whPerKm: number
        drives: number
      }
      smooth: {
        km: number
        whPerKm: number
        drives: number
      }
    }
  }
  matrix: {
    outsideC: [number, number]
    speedKmh: [number, number]
    whPerKm: number
    km: number
    drives: number
  }[]
  weeks: {
    week: string
    km: number
    whPerKm: number
    drives: number
  }[]
  byDistance: {
    km: (0 | 50 | 5 | 15 | 10000)[]
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  whPerKm?: number
  from?: string
  to?: string
  drives: number
  distanceKm: number
}
GET/v1/vehicles/:vehicleId/costs

What charging has cost in a range (at most three years, the default): the priced charges' cost, energy and count, by where the price came from, by kind of charge and by site (home, Supercharger, elsewhere), and period by period (by: day, week or month, default month, in the space's zone). A charge with no price of its own is priced by the space's tariffs (@cactive/vehicles-service/pricing: its place's tariff or the default, energy spread over its span) and counts in estimated too; one no tariff covers counts in unpriced, not as free, and noTariff says the space has no tariff at all. The same for every holder of costs (no routes or places, and the drive filters don't apply to charges); cost per km only for a caller who sees every drive (with any other range a caller could difference two ranges into a day's distance).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • by"day" | "week" | "month"

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 1096 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/costs?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated?: true
  totalCents: number
  expenses?: {
    count: number
    costCents: number
    byCategory: {
      count: number
      costCents: number
      category: string
    }[]
  }
  refuels?: {
    count: number
    litres: number
    costCents: number
  }
  centsPerKwh?: number
  fuel?: {
    [key: string]: number
  }
  centsPerKm?: number
  noTariff?: true
  from?: string
  to?: string
  currency: string
  timeZone: string
  by: "month" | "day" | "week"
  charges: number
  kwhAdded: number
  priced: {
    charges: number
    kwh: number
    costCents: number
  }
  estimated: {
    charges: number
    kwh: number
    costCents: number
  }
  unpriced: {
    charges: number
    kwh: number
  }
  bySource: {
    [key: string]: string | number
    charges: number
    kwh: number
    costCents: number
  }[]
  byKind: {
    [key: string]: string | number
    charges: number
    kwh: number
    costCents: number
  }[]
  bySite: {
    [key: string]: string | number
    charges: number
    kwh: number
    costCents: number
  }[]
  periods: {
    expenseCents?: number
    refuelCents?: number
    kwh: number
    unpricedKwh: number
    start: string
    charges: number
    costCents: number
    home: number
    supercharger: number
    other: number
  }[]
}
GET/v1/vehicles/:vehicleId/logbook

The business drives of a range for an ATO logbook (at most 15 months, the default): each one's date, odometer at the start and end, kilometres and purpose, oldest first, from the drives the caller sees. The summary says how many lack a purpose. Only a caller who sees every drive of every class gets what needs them all: business-use percent, the whole period's kilometres and odometer span, and the gaps (14 days or more with no drive); partial: true says the rest is from what they see. Whether the range is a valid logbook period (12 continuous weeks) is weeks and meetsTwelveWeeks. Storing a period is not built yet. all=1 lists the drives of every class the caller sees, each with its class (the Logbook page classifies them).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • all"0" | "1"

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 456 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/logbook?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated?: true
  openingOdometerKm?: number
  closingOdometerKm?: number
  totalKm?: number
  businessPercent?: number
  gaps?: {
    from: string
    to: string
  }[]
  from?: string
  to?: string
  weeks: number
  meetsTwelveWeeks: boolean
  partial: boolean
  trips: {
    manual?: true
    class?: null | "private" | "personal" | "business" | "commute"
    tripId: string
    date?: string
    startOdometerKm?: number
    endOdometerKm?: number
    km?: number
    purpose: null | string
  }[]
  businessTrips: number
  businessKm: number
  missingPurpose: number
}
PUT/v1/vehicles/:vehicleId/pins

The car's PINs for Valet Mode and Speed Limit Mode (docs/vehicles/commands.md → PINs): four digits each, which the car takes when the mode goes on and asks for to turn it off. The owner's alone; sealed with the car's key and never answered back.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • valetstringor null

    Matches ^\d{4}$.

  • speedLimitstringor null

    Matches ^\d{4}$.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/pins' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "valet": "example",
    "speedLimit": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  pinsSet: {
    valet: boolean
    speedLimit: boolean
  }
}
PUT/v1/vehicles/:vehicleId/details

The car's details beyond its name (docs/vehicles/settings.md → Vehicle), as Tessie's car info: its number plate, for whoever may change its settings, and the owner's notes (service, registration, insurance), the owner's alone and sealed with the car's key. null clears one; an empty note clears it too.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • platestringor null

    Matches ^[A-Z0-9][A-Z0-9 -]{0,11}$. Trimmed. Uppercased.

  • notesstringor null

    Up to 2,000 characters.

Also checked: Unknown fields are rejected. Say what to change: plate or notes.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/details' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "plate": "example",
    "notes": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  plate?: string
  notesSet?: boolean
}
GET/v1/vehicles/:vehicleId/settings

The car's settings that exist so far: its name and colour, whether its PINs are set (never the PINs), the key's state and the telemetry profile. PINs and the key are the owner's to know.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  notes?: string
  vin?: string
  pinsSet?: {
    speedLimit: boolean
    valet: boolean
  }
  keyStatus?: "pending" | "lost" | "paired" | "unpaired" | "not_required"
  telemetryProfile?: "standard" | "economy"
  plate?: string
  vehicleId: string
  name: string
  model?: string
  trim?: string
  year?: number
  colour?: string
}
GET/v1/vehicles/:vehicleId/commands

The commands sent to the car, newest first: the caller's own, and everyone's for a holder of share. K2's history; actor is named only for someone else's. next is sealed.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • cursorany JSONrequired
  • limitany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 366 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/commands?from=%7B%7D&to=%7B%7D&cursor=%7B%7D&limit=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  next?: string
  commands: {
    actorName?: string
    actor?: string
    mine: boolean
    parameterClasses?: string[]
    at?: string
    code?: string
    reason?: string
    commandId: string
    command: string
    via: "key" | "app" | "system" | "sentry" | "automation" | "caity"
    status: string
  }[]
}
PATCH/v1/vehicles/:vehicleId/trips

Classifies and tags drives in bulk: { ids (up to 50), class?, purpose? (null clears), tags? (replaces) }. Needs manage and trips, and only drives the caller sees change: an id that is missing, outside the car's period or hidden from the caller is in missing, the same for all three. Audited in an organisation's log (the change and how many, never the purpose).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • idsstring[]required

    1–50 items. Each matches ^drv_[0-9a-z]{8,40}$.

  • class"business" | "personal" | "commute" | "private"
  • purposeany JSONor null
  • tagsany JSON[]

    Up to 10 items.

  • addTagsany JSON[]

    Up to 10 items.

  • removeTagsany JSON[]

    Up to 10 items.

  • notesany JSONor null

Also checked: Say what to change: class, purpose, tags or notes. Give tags, or tags to add and remove, not both.

Errors

  • 400Not a vehicle id.
  • 400Send drives from at most 12 separate stretches at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PATCH 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  updated: string[]
  missing: string[]
}
POST/v1/vehicles/:vehicleId/trips/delete

Deletes drives for good ({ ids }, up to 50; docs/vehicles/app-drives.md → Deleting drives): their rows, routes, events and share links, a pending close, the driver's fleet pointers, then the days' totals rolled up again (@cactive/vehicles-service/drive-delete). The car's owner alone (the person, or the organisation's vehicles:admin) as a person in the app: a grantee 403 owner_only, an API key, Caity or the phone assistant 403 person_only; an ended period 409. A drive that isn't there, is outside the period or isn't shown to the caller is in missing. Audited in an organisation's log with the count, never which drives.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • idsstring[]required

    1–50 items. Each matches ^drv_[0-9a-z]{8,40}$.

Errors

  • 400Not a vehicle id.
  • 400Send drives from at most 12 separate stretches at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/delete' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  deleted: string[]
  missing: string[]
}
GET/v1/vehicles/:vehicleId/charges/:chargeId

One charge session: its summary (the place only for those who see places, the cost only for costs), how long, the average power and the charging efficiency (energy added over drawn), and its curve, power in kW and the state of charge every 30 seconds from curve.startedAt. For trips or costs, as the list. The curve carries no position. The cost by tariff period needs the tariff engine, which is not built, so a price is the one the charge has.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • chargeId

    A charge's id (chg_…), as the charges list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a charge id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Charge not found
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/charges/{chargeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  curve: null | {
    startedAt?: string
    stepS: number
    kw: number[]
    soc: number[]
  }
  centsPerKwh?: number
  efficiencyPct?: number
  avgKw?: number
  durationMin?: number
  byPeriod?: {
    flat?: {
      kwh: number
      cents: number
    }
    peak?: {
      kwh: number
      cents: number
    }
    shoulder?: {
      kwh: number
      cents: number
    }
    offpeak?: {
      kwh: number
      cents: number
    }
  }
  notes?: null | string
  odometerKm?: number
  litres?: number
  manual?: true
  privacy?: {
    hiddenFrom: string[]
  }
  place?: string
  costCents?: number
  costSource?: string
  tariffId?: string
  chargeId: string
  startedAt?: string
  endedAt?: string
  kind?: "other" | "home" | "work" | "supercharger"
  kwhAdded?: number
  kwhDrawn?: number
  socFrom?: number
  socTo?: number
  maxKw?: number
  maxAmps?: number
  volts?: number
  phases?: number
  cable?: "iec" | "sae" | "gb_ac" | "gb_dc"
  cellTempMinC?: number
  cellTempMaxC?: number
  heatedS?: number
}
PATCH/v1/vehicles/:vehicleId/charges/:chargeId

Overrides a charge's price or place: { costCents?, place? (null clears) }. Needs manage; a price needs costs and a place needs the sight of places (every drive of every class, or the owner). A price set by hand says costSource: "manual". Audited in an organisation's log.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • chargeId

    A charge's id (chg_…), as the charges list gives it.

Request body

  • costCentsinteger

    0–1000000.

  • placeany JSONor null

Also checked: Say what to change: costCents or place.

Errors

  • 400Not a vehicle id.
  • 400Not a charge id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Charge not found
  • 409This car's period has ended.
curl -X PATCH 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/charges/{chargeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "costCents": 1,
    "place": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  place?: null | string
  costCents?: number
  costSource?: string
  chargeId: string
}
GET/v1/vehicles/:vehicleId/activity/series

Activity's charts (docs/vehicles/insights.md → Routes): the battery, power (driving draws, regenerating and charging add, so charging is negative) and speed through at most two days, a point a minute, from the drives the caller sees and the charges' curves. view opens it; each part needs its own capability.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most two days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/activity/series?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  from?: string
  to?: string
  points: {
    t: number
    soc?: number
    kw?: number
    speedKmh?: number
  }[]
}
GET/v1/vehicles/:vehicleId/analytics/drives

Drives by local day, week or month (trips; Analytics in docs/vehicles/insights.md).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • by"day" | "week" | "month"

Errors

  • 400Not a vehicle id.
  • 400Ask for at most … days ….
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/analytics/drives?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated: boolean
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: undefined
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
  }
  periods: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  hidden: boolean
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
  }
  periods: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
}
GET/v1/vehicles/:vehicleId/analytics/charges

Charging by local day, week or month (trips or costs, the cost with costs).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • by"day" | "week" | "month"

Errors

  • 400Not a vehicle id.
  • 400Ask for at most … days ….
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/analytics/charges?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated: boolean
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: undefined
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
  }
  periods: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  hidden: boolean
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
  }
  periods: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
}
GET/v1/vehicles/:vehicleId/analytics/parked

Parked periods by local day, week or month (trips, for a caller who sees every drive).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired
  • by"day" | "week" | "month"

Errors

  • 400Not a vehicle id.
  • 400Ask for at most … days ….
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/analytics/parked?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated: boolean
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: undefined
  total: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
  }
  periods: {
    drives: number
    distanceKm: number
    assistedKm?: number
    assistedOfKm?: number
    styleScore?: number
    energyKwh: number
    minutes: number
    whPerKm?: number
    avgSpeedKmh?: number
    maxSpeedKmh?: number
    rangeEfficiency?: number
    costCents?: number
    fuelCents?: number
    start: string
  }[]
  speedBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  temperatureBands: {
    from: number
    to: number
    whPerKm: number
    distanceKm: number
    drives: number
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
  }
  periods: {
    charges: number
    kwhAdded: number
    kwhDrawn?: number
    drawnCharges?: number
    efficiency?: number
    rangeAddedKm?: number
    minutes: number
    home: number
    supercharger: number
    other: number
    costCents?: number
    centsPerKwh?: number
    priced?: number
    fuelCents?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  hidden: boolean
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
} | {
  truncated?: boolean
  total: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
  }
  periods: {
    parked: number
    hours: number
    kwhLost: number
    socLostPct: number
    kwhPerDay?: number
    sentry?: number
    climate?: number
    asleep?: number
    start: string
  }[]
  kind: "drives" | "parked" | "charges"
  from?: string
  to?: string
  by: "month" | "day" | "week"
  timeZone: string
  currency: string
}
PUT/v1/vehicles/:vehicleId/battery

The battery pack, as the owner knows it (Battery Health): { packDate?: "YYYY-MM-DD" | null, originalKwh?: number | null }, the install date (not after today) and the capacity new (20 to 250 kWh); null clears one. Needs settings; audited as vehicle.settings_update (change: "battery").

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • packDatestringor null

    Matches ^\d{4}-\d{2}-\d{2}$.

  • originalKwhnumberor null

    20–250.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400The pack's date can't be in the future.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/battery' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "packDate": "2026-01-01",
    "originalKwh": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  originalKwh?: number
  date?: string
}
GET/v1/vehicles/:vehicleId/maintenance

The car's maintenance (docs/vehicles/insights-alerts.md → Maintenance): each item's interval (limit rows), when it was last done as the owner set it, and whether it is due, soon or not known. The odometer (a distance item's due reading) only where the driving state shows. view.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/maintenance' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  odometerKm?: number
  items: {
    item: "tyre_rotation" | "brake_fluid" | "brake_calipers" | "cabin_filter" | "ac_desiccant"
    every: number
    by: "months" | "km"
    last?: {
      on: string
      odometerKm?: number
    }
    dueOn?: string
    dueAtKm?: number
    status: "ok" | "unknown" | "due" | "soon"
  }[]
}
PUT/v1/vehicles/:vehicleId/maintenance

Marks an item done ({ item, on: "YYYY-MM-DD", odometerKm? }, not after today; the odometer for the tyre rotation, the car's reading now when left out) or clears it (on: null). Needs settings; audited as vehicle.settings_update (change: maintenance).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • item"tyre_rotation" | "brake_fluid" | "brake_calipers" | "cabin_filter" | "ac_desiccant"required
  • onstringrequiredor null

    Matches ^\d{4}-\d{2}-\d{2}$.

  • odometerKminteger

    0–2000000.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400It can't be done in the future.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/maintenance' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "item": "tyre_rotation",
    "on": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  odometerKm?: number
  items: {
    item: "tyre_rotation" | "brake_fluid" | "brake_calipers" | "cabin_filter" | "ac_desiccant"
    every: number
    by: "months" | "km"
    last?: {
      on: string
      odometerKm?: number
    }
    dueOn?: string
    dueAtKm?: number
    status: "ok" | "unknown" | "due" | "soon"
  }[]
}
GET/v1/vehicles/:vehicleId/costs/projection

This month's and year's charging cost, projected from the last 28 days (and last year's season), for holders of costs.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/costs/projection' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  recommendations?: {
    id: "plan" | "schedule" | "home" | "sentry" | "rate" | "wheels" | "tyres"
    status: "ok" | "fix" | "learning"
    savedCents?: number
    yearCents?: number
    start?: string
    tariffId?: string
    name?: string
    kwh?: number
    inches?: number
    reason?: "no_rate" | "few_charges" | "one_rate" | "flat_rate" | "few_parked" | "no_pressures"
    ignored?: boolean
    wheels?: {
      wheel: "fl" | "fr" | "rl" | "rr"
      watch: "low" | "leak"
      perDay: number
      underOthers: number
    }[]
  }[]
  split?: {
    home: number
    supercharger: number
    other: number
  }
  timing?: {
    charges: number
    savedCents: number
    yearCents: number
    start?: string
    zone: string
  }
  centsPerKm?: number
  noTariff?: boolean
  unpriced: {
    charges: number
    kwh: number
  }
  month: {
    month: string
    soFarCents: number
    projectedCents: number
    dailyCents: number
    daysLeft: number
    ratio: number
  }
  year: {
    year: string
    soFarCents: number
    projectedCents: number
  }
  annualCents: number
  fiveYearsCents: number
  basisDays: number
  rough: boolean
  seasonal: boolean
  currency: string
  timeZone: string
  today: string
}
PUT/v1/vehicles/:vehicleId/recommendations

Replaces the cost recommendations the caller ignores for the car: { ignored: [id] } (none removes the row). People in the apps; costs on the car, as the projection that shows them.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • ignored("home" | "rate" | "schedule" | "plan" | "sentry" | "tyres" | "wheels")[]required

    Up to 7 items.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Only a person can choose these.
  • 403Choose these in the app.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/recommendations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ignored": [
      "home"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  ignored: ("plan" | "schedule" | "home" | "sentry" | "rate" | "wheels" | "tyres")[]
}
GET/v1/vehicles/:vehicleId/alerts

The caller's own alerts for the car (docs/vehicles/insights-alerts.md): what they chose (nothing until they do) and which kinds they may choose. People in the apps only; view on the car.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Only a person can choose these.
  • 403Choose these in the app.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/alerts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  choice: {
    kinds: ("arrive" | "leave" | "moved" | "sentry" | "alarm" | "software" | "unlocked" | "car_alert" | "rain_open" | "windows_open" | "valet_on" | "key_added" | "climate_safety" | "drive_start" | "drive_end" | "speed_over" | "odometer_over" | "charge_start" | "charge_complete" | "charge_end" | "charge_stopped" | "reduced_power" | "no_power" | "battery_low" | "not_plugged_in" | "tyre_low" | "tyre_warning" | "tyre_leak" | "maintenance")[]
    unlockedMinutes: number
    unlockedAtHome: boolean
    batteryBelowPct: number
    speedOverKmh: number
    odometerOverKm?: number
    climateAboveC: number
    tyreBelowKpa: number
  }
  available: ("arrive" | "leave" | "moved" | "sentry" | "alarm" | "software" | "unlocked" | "car_alert" | "rain_open" | "windows_open" | "valet_on" | "key_added" | "climate_safety" | "drive_start" | "drive_end" | "speed_over" | "odometer_over" | "charge_start" | "charge_complete" | "charge_end" | "charge_stopped" | "reduced_power" | "no_power" | "battery_low" | "not_plugged_in" | "tyre_low" | "tyre_warning" | "tyre_leak" | "maintenance")[]
}
PUT/v1/vehicles/:vehicleId/alerts

Replaces the caller's alerts for the car: { kinds, unlockedMinutes, batteryBelowPct }. A kind they may not choose is 403; no kinds removes the row. Who they are now is kept with it, so each alert is checked against their access when it fires.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Only a person can choose these.
  • 403Choose these in the app.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/alerts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  choice: {
    kinds: ("arrive" | "leave" | "moved" | "sentry" | "alarm" | "software" | "unlocked" | "car_alert" | "rain_open" | "windows_open" | "valet_on" | "key_added" | "climate_safety" | "drive_start" | "drive_end" | "speed_over" | "odometer_over" | "charge_start" | "charge_complete" | "charge_end" | "charge_stopped" | "reduced_power" | "no_power" | "battery_low" | "not_plugged_in" | "tyre_low" | "tyre_warning" | "tyre_leak" | "maintenance")[]
    unlockedMinutes: number
    unlockedAtHome: boolean
    batteryBelowPct: number
    speedOverKmh: number
    odometerOverKm?: number
    climateAboveC: number
    tyreBelowKpa: number
  }
  available: ("arrive" | "leave" | "moved" | "sentry" | "alarm" | "software" | "unlocked" | "car_alert" | "rain_open" | "windows_open" | "valet_on" | "key_added" | "climate_safety" | "drive_start" | "drive_end" | "speed_over" | "odometer_over" | "charge_start" | "charge_complete" | "charge_end" | "charge_stopped" | "reduced_power" | "no_power" | "battery_low" | "not_plugged_in" | "tyre_low" | "tyre_warning" | "tyre_leak" | "maintenance")[]
}
GET/v1/vehicles/:vehicleId/export

The car's data as files: kind one of drives, charges, parked, events, commands, tyres, battery or logbook as CSV, or all (the default) as a ZIP of every kind the caller may see with a README. A range of at most three years (default the last year). Each kind follows its page's rule: drives and the logbook need trips (the drives the caller sees), charges trips or costs (the price only with costs), parked periods, tyres and events every drive; places are names, and positions only for the owner. 413 past the size one answer holds. Audited (vehicle.export).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • kindany
  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most three years at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 413That's more than one download holds. Choose a shorter range.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/export?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200 with no body

GET/v1/vehicles/:vehicleId/keys

The keychain as last read, labelled, and the state of the read. The table only: open apps poll it while a read runs.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/keys' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  keyCount: null | number
  maxKeys: number
  readable: boolean
  entries: {
    keyId: string
    slot: number
    kind: "app" | "phone" | "unread" | "this_app" | "key_card" | "driver_phone" | "fob_or_phone"
    label: string
    role: null | string
    driverId: null | string
    leaving: boolean
    firstSeenAt?: string
  }[]
  readAt: null | string
  reading: boolean
  lastOutcome: null | "ok" | "partial" | "failed" | "rate_limited" | "refused" | "reconnect" | "asleep"
  lastTriedAt: null | string
  countChanged: boolean
  nextReadAt: null | string
  howToUrl: string
}
POST/v1/vehicles/:vehicleId/keys/read

Reads the car's keychain again: 202 and a vehicles.keys_read job. Tesla bills each question and the car must be awake (it is never woken for this). 429 with Retry-After inside the cooldown or while a read runs; 409 for a car that doesn't use Tesla's command protocol (pre-2021 Model S and X).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/keys/read' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  queued: true
}
GET/v1/vehicles/:vehicleId/drivers

The car's Tesla drivers and pending invitations (Tesla's sharing in its own app), each driver with how many of their keys were on the car when it was last read. A car added with a driver's account (not_owner), a connection whose scopes Tesla refuses (not_allowed) or one that needs signing in again (reconnect) is available: false with the reason, so the page still shows the rest.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/drivers' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  available: false
  reason: string
  drivers: []
  invitations: []
}
| {
  available: true
  drivers: {
    driverId: string
    name: string
    keysOnCar: number
  }[]
  invitations: {
    inviteId: string
    link: null | string
    expiresAt: null | string
  }[]
}
POST/v1/vehicles/:vehicleId/drivers/invitations

A single-use link to Tesla's app that makes its account a driver of the car for good (it lapses unused after 24 hours). Step-up; audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/drivers/invitations' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 201

{
  inviteId: string
  link?: string
  expiresAt: null | string
}
POST/v1/vehicles/:vehicleId/drivers/invitations/:inviteId/revoke

Revokes a pending invitation: its link stops working. It only takes access away, so no step-up; audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • inviteId

    Invite id (inv_…); under vehicles, Tesla's id for a driver invitation, as the drivers list gives it.

Errors

  • 400Not a invitation id.
  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/drivers/invitations/{inviteId}/revoke' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  revoked: true
}
DELETE/v1/vehicles/:vehicleId/drivers/:driverId

Removes a Tesla driver: their access in Tesla's app, and their phone keys on the car when it is next online. Step-up; audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • driverId

    A Tesla driver's id, as Tesla gives it (digits): the car's drivers list names it.

Errors

  • 400Not a driver id.
  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/drivers/{driverId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: true
}
GET/v1/vehicles/:vehicleId/data

The car's last read and the state of the read: battery and climate (what the stream doesn't carry), schedules (charging and preconditioning, without where they apply), and raw, every field by section, for those who hold the car through its space (null for anyone else). The table only: open pages poll it while a read runs.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/data' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  readAt: null | string
  reading: boolean
  lastOutcome: null | "ok" | "failed" | "rate_limited" | "reconnect" | "asleep"
  lastTriedAt: null | string
  nextReadAt?: null | string
  battery: null | {
    chargingState?: string
    usableSoc?: number
    idealRangeKm?: number
    chargerVolts?: number
    chargerAmps?: number
    chargerKw?: number
    chargerPhases?: number
    ampsRequest?: number
    ampsMax?: number
    energyAddedKwh?: number
    minutesToFull?: number
    heaterOn?: boolean
    cable?: string
    fastCharger?: boolean
    scheduledMode?: string
  }
  climate: null | {
    on?: boolean
    preconditioning?: boolean
    driverC?: number
    passengerC?: number
    minC?: number
    maxC?: number
    seats: {
      seat: number
      label: string
      level: number
    }[]
    wheelHeater?: boolean
    keeper?: "off" | "on" | "dog" | "camp"
    overheat?: "off" | "on" | "fan_only"
    overheatLevel?: "low" | "medium" | "high"
    defrost?: boolean
    bioweapon?: boolean
  }
  schedules: null | {
    charge: null | {
      name: null | string
      place: null | string
      id: number
      days: ("Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat")[]
      oneTime: boolean
      enabled: boolean
      startMinutes?: number
      endMinutes?: number
      preconditionMinutes?: number
    }[]
    precondition: null | {
      name: null | string
      place: null | string
      id: number
      days: ("Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat")[]
      oneTime: boolean
      enabled: boolean
      startMinutes?: number
      endMinutes?: number
      preconditionMinutes?: number
    }[]
  }
  raw: null | {
    [key: string]: {
      [key: string]: unknown
    }
  }
  rawShown: boolean
}
POST/v1/vehicles/:vehicleId/data/read

Reads the car again: 202 and a vehicles.data_read job. Tesla bills each read (and one of a car that isn't online, so the worker asks Tesla's free car list first); the car is never woken for this. 429 with Retry-After inside the cooldown, while a read runs (rate_limited) or past the car's reads for the day (daily_limit).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/data/read' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  queued: true
}
GET/v1/vehicles/:vehicleId/software

The car's software: the version now, the update it reports, and the versions it has reported (software.ts): installs newest first, days since the last and the average gap.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/software' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  version: null | string
  update: null | {
    status: "scheduled" | "available" | "downloading" | "installing"
    version: string
    minutes?: number
    percent?: number
  }
  upToDate: boolean | null
  firstSeen: null | {
    version: string
    at: null | string
  }
  installs: {
    version: string
    at?: string
    daysAfter: null | number
  }[]
  daysSince: null | number
  averageDays: null | number
}
POST/v1/vehicles/:vehicleId/schedules/:kind

Adds a schedule where the car is now (charging: charge; preconditioning: climate), through the command service. The position is the car's own, read here and never sent back. 409 no_position while the car hasn't reported one.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • kind

    What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.

Request body

  • days("Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat")[]

    1–7 items.

  • enabledboolean
  • oneTimeboolean
  • startMinutesintegeror null

    0–1439.

  • endMinutesintegeror null

    0–1439.

  • preconditionMinutesinteger

    0–1439.

Also checked: Unknown fields are rejected.

Errors

  • 400Send an Idempotency-Key header, so a repeated request returns the first result.
  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Not a kind of schedule.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/schedules/{kind}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "days": [
      "Sun"
    ],
    "enabled": true,
    "oneTime": true
  }'
Send it from this page with your session or a key.
PUT/v1/vehicles/:vehicleId/schedules/:kind/:scheduleId

Changes a schedule from the car's last read (only what is sent changes), where it applies kept. 404 for one the read doesn't have.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • kind

    What the resource is: project (a Serverless App Service), database, bucket, domain, repository or agent; under vehicles the kind of schedule, charge or precondition.

  • scheduleId

    A car's schedule, by Tesla's id for it, as the car's last read (…/data) lists it.

Request body

  • days("Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat")[]

    1–7 items.

  • enabledboolean
  • oneTimeboolean
  • startMinutesintegeror null

    0–1439.

  • endMinutesintegeror null

    0–1439.

  • preconditionMinutesinteger

    0–1439.

Also checked: Unknown fields are rejected. Send what changes.

Errors

  • 400Not a schedule id.
  • 400Send an Idempotency-Key header, so a repeated request returns the first result.
  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Not a kind of schedule.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/schedules/{kind}/{scheduleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "days": [
      "Sun"
    ],
    "enabled": true,
    "oneTime": true
  }'
Send it from this page with your session or a key.
GET/v1/vehicles/:vehicleId/imports

The car's imports, newest first.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  imports: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }[]
}
POST/v1/vehicles/:vehicleId/imports

A new import and an upload link per file (one key, length and SHA-256, an hour). 413 over a limit, 409 import_open, 429 past the day's.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • source"tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"required
  • filesobject[]required

    1–1,000 items.

  • files[].namestringrequired

    1–200 characters. Trimmed.

  • files[].bytesintegerrequired

    1–17179869184.

  • files[].sha256stringrequired

    Matches ^[A-Za-z0-9+/]{43}=$.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "tessie_export",
    "files": [
      {
        "name": "Example",
        "bytes": 1,
        "sha256": "example"
      }
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  importId: string
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
  uploads: {
    url: string
    headers: {
      [key: string]: string
    }
  }[]
}
POST/v1/vehicles/:vehicleId/imports/:importId/check

Checks each upload's size and checksum, then queues the check (again with new options): 202.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Request body

  • timeZonestring

    1–64 characters. Trimmed.

  • currencystring

    Matches ^[A-Z]{3}$.

  • businessTagsstring[]

    Up to 20 items. Each 1–40 characters, trimmed.

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}/check' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "timeZone": "example",
    "currency": "example",
    "businessTags": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 202

{
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
}
GET/v1/vehicles/:vehicleId/imports/:importId

Status, progress, the summary and the problems.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Import not found.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
}
GET/v1/vehicles/:vehicleId/imports/:importId/rows

The first 200 new rows of a kind, as they will read; places only with location.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Query parameters

  • kind"drive" | "charge" | "idle"required

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Import not found.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}/rows?kind=drive' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  rows: {
    start?: {
      name: null | string
      lat: null | number
      lon: null | number
    }
    end?: {
      name: null | string
      lat: null | number
      lon: null | number
    }
    track?: boolean
    id: string
    kind: "drive" | "charge" | "idle"
    startedAt?: string
    endedAt?: string
    chargeKind?: unknown
    place?: {
      name: null | string
      lat: null | number
      lon: null | number
    }
  }[]
  places: boolean
}
POST/v1/vehicles/:vehicleId/imports/:importId/commit

Commits the check named by version: 202; 409 stale for an older one, confirm_skip until invalid rows' skipping is confirmed.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Request body

  • versionintegerrequired

    ≥ 1.

  • skipInvalidboolean

    Default false.

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}/commit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1
  }'
Send it from this page with your session or a key.

Response 202

{
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
}
POST/v1/vehicles/:vehicleId/imports/:importId/undo

Undoes a committed import: its rows go, edits since included. 202.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}/undo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
}
DELETE/v1/vehicles/:vehicleId/imports/:importId

Cancels an import before it commits. 202.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a import id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/imports/{importId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  import: {
    importId: string
    source: "tessie_export" | "tessie_template" | "vehicles_csv" | "teslafi" | "teslamate"
    status: "ready" | "expired" | "done" | "failed" | "cancelled" | "uploading" | "refused" | "checking" | "importing" | "undoing" | "undone"
    version: number
    progress: number
    files: {
      name: string
      bytes: number
    }[]
    fileNames: string[]
    options: {
      timeZone?: string
      currency?: string
      businessTags?: string[]
      recentMs?: number
    }
    summary: null | {
      from?: string
      to?: string
      kinds: {
        drive: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        battery: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        charge: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        idle: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
        tyre: {
          new: number
          duplicate: number
          short: number
          recent: number
          invalid: number
          incomplete: number
        }
      }
      rows: number
      invalidRows: number
      distanceKm: number
      kwhUsed: number
      kwhAdded: number
      drivesByMonth: {
        [key: string]: number
      }
      carCheck: "vin" | "odometer"
      locations: boolean
      units?: "km" | "mi"
      timeZone?: string
      repeatedHour: number
      trimmed: number
    }
    problems: {
      file: number
      row: number
      column?: string
      code: string
    }[]
    problemCount: number
    refusal: null | {
      at?: string
      code: string
      file?: number
      missing?: string[]
      unexpected?: string[]
      limit?: string
    }
    from: null | string
    to: null | string
    written: number
    createdAt?: string
    checkedAt: null | string
    committedAt: null | string
    undoneAt: null | string
  }
}
PUT/v1/vehicles/:vehicleId/manual

A manual car's make, model, year and fuel (null clears the model or the year): settings, the same as its name.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • makestring

    1–40 characters.

  • modelstringor null

    Up to 60 characters.

  • yearintegeror null
  • fuel"electric" | "petrol" | "diesel" | "hybrid" | "plugin_hybrid"

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/manual' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "make": "example",
    "model": "example",
    "year": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  make?: string
  model: null | string
  year: null | number
  fuel?: "electric" | "petrol" | "diesel" | "hybrid" | "plugin_hybrid"
}
POST/v1/vehicles/:vehicleId/log/drives

Logs a drive by hand: 201 { trip }, the drive as the list shows it. 409 overlaps when another drive covers any of it.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • startedAtstringrequired

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • endedAtstringrequired

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • distanceKmnumber

    0–2000000.

  • startOdometerKmnumber

    0–2000000.

  • endOdometerKmnumber

    0–2000000.

  • fromobject
  • from.namestring

    Up to 200 characters.

  • from.latnumber

    -90–90.

  • from.lonnumber

    -180–180.

  • toobject
  • to.namestring

    Up to 200 characters.

  • to.latnumber

    -90–90.

  • to.lonnumber

    -180–180.

  • pathobject[]

    Up to 5,000 items.

  • path[].latnumberrequired

    -90–90.

  • path[].lonnumberrequired

    -180–180.

  • class"business" | "personal" | "commute" | "private"
  • purposeany JSON
  • tagsstring[]

    Up to 10 items. Each 1–30 characters.

  • notesany JSON

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/drives' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "startedAt": "2026-01-01",
    "endedAt": "2026-01-01"
  }'
Send it from this page with your session or a key.

Response 201

{
  trip: {
    hasTrack: boolean
    path?: {
      lat: number
      lon: number
    }[]
    privacy?: {
      hiddenFrom: string[]
      speedHiddenFrom: string[]
    }
    endsHidden?: true
    startPlace?: string
    endPlace?: string
    secondsOver?: {
      [key: string]: number
    }
    kmOver?: {
      [key: string]: number
    }
    score?: number
    harshAccel?: number
    harshBraking?: number
    harshCornering?: number
    style?: {
      pedalS?: number
      pedalAvgPct?: number
      heavyS?: number
      brakes?: number
      cruiseS?: number
      score?: number
    }
    weather?: string
    mine: boolean
    notes?: null | string
    startOdometerKm?: number
    endOdometerKm?: number
    manual?: true
    imported?: true
    assistedKm?: number
    class?: "private" | "personal" | "business" | "commute"
    purpose?: string
    tags?: string[]
    driverId?: string
    outsideCMin?: number
    outsideCMax?: number
    elevationGainM?: number
    elevationLossM?: number
    maxSpeedKmh?: number
    avgMovingSpeedKmh?: number
    tripId: string
    startedAt?: string
    endedAt?: string
    distanceKm?: number
    energyKwh?: number
    whPerKm?: number
    socFrom?: number
    socTo?: number
    placesHidden?: boolean
    speedHidden?: boolean
  }
}
PATCH/v1/vehicles/:vehicleId/log/drives/:tripId

Changes a drive made by hand (all but its start and route; null clears). 409 not_manual for a recorded drive.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Request body

  • endedAtstring

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • distanceKmnumber

    0–2000000.

  • startOdometerKmnumberor null

    0–2000000.

  • endOdometerKmnumberor null

    0–2000000.

  • fromobjector null
  • from.namestring

    Up to 200 characters.

  • from.latnumber

    -90–90.

  • from.lonnumber

    -180–180.

  • toobjector null
  • to.namestring

    Up to 200 characters.

  • to.latnumber

    -90–90.

  • to.lonnumber

    -180–180.

  • class"business" | "personal" | "commute" | "private"or null
  • purposeany JSONor null
  • tagsstring[]

    Up to 10 items. Each 1–30 characters.

  • notesany JSONor null

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PATCH 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/drives/{tripId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "endedAt": "2026-01-01",
    "distanceKm": 1,
    "startOdometerKm": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  trip: {
    hasTrack: boolean
    path?: {
      lat: number
      lon: number
    }[]
    privacy?: {
      hiddenFrom: string[]
      speedHiddenFrom: string[]
    }
    endsHidden?: true
    startPlace?: string
    endPlace?: string
    secondsOver?: {
      [key: string]: number
    }
    kmOver?: {
      [key: string]: number
    }
    score?: number
    harshAccel?: number
    harshBraking?: number
    harshCornering?: number
    style?: {
      pedalS?: number
      pedalAvgPct?: number
      heavyS?: number
      brakes?: number
      cruiseS?: number
      score?: number
    }
    weather?: string
    mine: boolean
    notes?: null | string
    startOdometerKm?: number
    endOdometerKm?: number
    manual?: true
    imported?: true
    assistedKm?: number
    class?: "private" | "personal" | "business" | "commute"
    purpose?: string
    tags?: string[]
    driverId?: string
    outsideCMin?: number
    outsideCMax?: number
    elevationGainM?: number
    elevationLossM?: number
    maxSpeedKmh?: number
    avgMovingSpeedKmh?: number
    tripId: string
    startedAt?: string
    endedAt?: string
    distanceKm?: number
    energyKwh?: number
    whPerKm?: number
    socFrom?: number
    socTo?: number
    placesHidden?: boolean
    speedHidden?: boolean
  }
}
DELETE/v1/vehicles/:vehicleId/log/drives/:tripId

Deletes a drive made by hand, as any drive goes (its links and photos too). 204.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/drives/{tripId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

POST/v1/vehicles/:vehicleId/log/charges

Logs a charge (kWh) or a refuel (litres) by hand: 201 { charge }. A price needs costs too. 409 overlaps.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • type"charge" | "refuel"required
  • startedAtstringrequired

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • endedAtstring

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • kind"home" | "work" | "supercharger" | "other"
  • kwhAddednumber

    0–250.

  • litresnumber

    0–500.

  • costCentsinteger

    0–100000000.

  • socFrominteger

    0–100.

  • socTointeger

    0–100.

  • odometerKmnumber

    0–2000000.

  • placeobject
  • place.namestring

    Up to 200 characters.

  • place.latnumber

    -90–90.

  • place.lonnumber

    -180–180.

  • notesany JSON

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/charges' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "charge",
    "startedAt": "2026-01-01"
  }'
Send it from this page with your session or a key.

Response 201

{
  charge: {
    notes?: null | string
    odometerKm?: number
    litres?: number
    manual?: true
    privacy?: {
      hiddenFrom: string[]
    }
    place?: string
    costCents?: number
    costSource?: string
    tariffId?: string
    chargeId: string
    startedAt?: string
    endedAt?: string
    kind?: "other" | "home" | "work" | "supercharger"
    kwhAdded?: number
    kwhDrawn?: number
    socFrom?: number
    socTo?: number
    maxKw?: number
    maxAmps?: number
    volts?: number
    phases?: number
    cable?: "iec" | "sae" | "gb_ac" | "gb_dc"
    cellTempMinC?: number
    cellTempMaxC?: number
    heatedS?: number
  }
}
PATCH/v1/vehicles/:vehicleId/log/charges/:chargeId

Changes a charge or refuel made by hand (all but its start and type; null clears): { charge }. A price needs costs; 409 not_manual for a recorded one.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • chargeId

    A charge's id (chg_…), as the charges list gives it.

Request body

  • endedAtstringor null

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • kind"home" | "work" | "supercharger" | "other"
  • kwhAddednumber

    0–250.

  • litresnumber

    0–500.

  • costCentsintegeror null

    0–100000000.

  • socFromintegeror null

    0–100.

  • socTointegeror null

    0–100.

  • odometerKmnumberor null

    0–2000000.

  • placeobjector null
  • place.namestring

    Up to 200 characters.

  • place.latnumber

    -90–90.

  • place.lonnumber

    -180–180.

  • notesany JSONor null

Errors

  • 400Not a vehicle id.
  • 400Not a charge id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PATCH 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/charges/{chargeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "endedAt": "2026-01-01",
    "kind": "home",
    "kwhAdded": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  charge: {
    notes?: null | string
    odometerKm?: number
    litres?: number
    manual?: true
    privacy?: {
      hiddenFrom: string[]
    }
    place?: string
    costCents?: number
    costSource?: string
    tariffId?: string
    chargeId: string
    startedAt?: string
    endedAt?: string
    kind?: "other" | "home" | "work" | "supercharger"
    kwhAdded?: number
    kwhDrawn?: number
    socFrom?: number
    socTo?: number
    maxKw?: number
    maxAmps?: number
    volts?: number
    phases?: number
    cable?: "iec" | "sae" | "gb_ac" | "gb_dc"
    cellTempMinC?: number
    cellTempMaxC?: number
    heatedS?: number
  }
}
DELETE/v1/vehicles/:vehicleId/log/charges/:chargeId

Deletes a charge or refuel made by hand, the days' totals following: 204. 409 not_manual for a recorded one.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • chargeId

    A charge's id (chg_…), as the charges list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a charge id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/charges/{chargeId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/log/entries

The car's log, newest first: odometer readings and services for trips, expenses for trips and costs too (an expense is a cost), with the cost only for costs, the odometer with the driving state, and notes and places where place names show. kind filters.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromstring

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • tostring

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • kind"odometer" | "expense" | "service"
  • cursorstring

    Up to 2,000 characters.

  • limitinteger

    1–100. Coerced from a string.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/entries' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  next?: string
  entries: {
    editedAt?: string
    note?: null | string
    place?: null | string
    items?: string[]
    category?: "other" | "registration" | "toll" | "parking" | "insurance" | "cleaning"
    costCents?: number
    odometerKm?: number
    entryId: string
    at?: string
    kind: "service" | "odometer" | "expense"
  }[]
}
POST/v1/vehicles/:vehicleId/log/entries

Logs an odometer reading, an expense or a service: 201 { entry }. An expense, or a price on a service, needs costs too.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • kind"odometer" | "expense" | "service"required
  • atstringrequired

    Matches ^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$.

  • odometerKmnumber

    0–2000000.

  • costCentsinteger

    0–100000000.

  • category"toll" | "parking" | "insurance" | "registration" | "cleaning" | "other"
  • items("tyre_rotation" | "brake_fluid" | "brake_calipers" | "cabin_filter" | "ac_desiccant")[]

    Up to 5 items.

  • noteany JSON
  • placeobject
  • place.namestring

    Up to 200 characters.

  • place.latnumber

    -90–90.

  • place.lonnumber

    -180–180.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/entries' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "odometer",
    "at": "example"
  }'
Send it from this page with your session or a key.

Response 201

{
  entry: {
    editedAt?: string
    note?: null | string
    place?: null | string
    items?: string[]
    category?: "other" | "registration" | "toll" | "parking" | "insurance" | "cleaning"
    costCents?: number
    odometerKm?: number
    entryId: string
    at?: string
    kind: "service" | "odometer" | "expense"
  }
}
PATCH/v1/vehicles/:vehicleId/log/entries/:entryId

Changes an odometer reading, expense or service (all but its kind and day; null clears): { entry }. An expense needs costs too.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • entryId

    A meal on the plan (fpe_…); under vehicles an entry of a car's log made by hand (vlg_…), as the log lists it.

Request body

  • odometerKmnumberor null

    0–2000000.

  • costCentsintegeror null

    0–100000000.

  • category"toll" | "parking" | "insurance" | "registration" | "cleaning" | "other"
  • items("tyre_rotation" | "brake_fluid" | "brake_calipers" | "cabin_filter" | "ac_desiccant")[]

    Up to 5 items.

  • noteany JSONor null
  • placeobjector null
  • place.namestring

    Up to 200 characters.

  • place.latnumber

    -90–90.

  • place.lonnumber

    -180–180.

Errors

  • 400Not a entry id.
  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PATCH 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/entries/{entryId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "odometerKm": 1,
    "costCents": 1,
    "category": "toll"
  }'
Send it from this page with your session or a key.

Response 200

{
  entry: {
    editedAt?: string
    note?: null | string
    place?: null | string
    items?: string[]
    category?: "other" | "registration" | "toll" | "parking" | "insurance" | "cleaning"
    costCents?: number
    odometerKm?: number
    entryId: string
    at?: string
    kind: "service" | "odometer" | "expense"
  }
}
DELETE/v1/vehicles/:vehicleId/log/entries/:entryId

Deletes an entry of the log: 204. A service's maintenance days stay; an expense the caller can't see is 404.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • entryId

    A meal on the plan (fpe_…); under vehicles an entry of a car's log made by hand (vlg_…), as the log lists it.

Errors

  • 400Not a vehicle id.
  • 400Not a entry id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/log/entries/{entryId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/privacy

{ privacy }: what the owner hides from everyone they share the car with (absent fields: each share decides).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/privacy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  privacy: {
    pausedUntil?: number
    locationPrecision?: "hidden" | "exact" | "approximate"
    drivingState?: "hidden" | "shown"
    speedLive?: "hidden" | "shown"
    speedDrives?: "hidden" | "shown"
    placeNames?: "hidden" | "shown"
    music?: "hidden" | "shown"
    tripsVisible?: "none" | "all"
    chargesVisible?: "none" | "all"
  }
}
PUT/v1/vehicles/:vehicleId/privacy

Changes the for-everyone settings: a field set caps every share, null leaves it to each share, absent keeps it. pausedUntil pauses every share until then (forever: until turned back on), null resumes. Audited (vehicle.settings_update, privacy, the fields changed, never their values).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • pausedUntilinteger | "forever"or null

    > 0, ≤ 253402300799.

  • locationPrecisionany JSONrequired
  • drivingStateany JSONrequired
  • speedLiveany JSONrequired
  • speedDrivesany JSONrequired
  • placeNamesany JSONrequired
  • musicany JSONrequired
  • tripsVisibleany JSONrequired
  • chargesVisibleany JSONrequired

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400A pause ends in the future, or not until it's turned back on.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/privacy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "locationPrecision": {},
    "drivingState": {},
    "speedLive": {},
    "speedDrives": {},
    "placeNames": {},
    "music": {},
    "tripsVisible": {},
    "chargesVisible": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  privacy: {
    [key: string]: unknown
  }
}
GET/v1/vehicles/:vehicleId/data-policy

{ policy }: the car's data policy (docs/vehicles/privacy.md → Data controls); absent fields are today's behaviour. The owner's alone.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/data-policy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  policy: {
    location?: {
      org?: "hidden" | "exact" | "approximate"
      maps?: "hidden" | "exact" | "approximate"
      you?: "hidden" | "exact" | "approximate"
    }
    retention?: {
      photos?: number
      charging?: number
      positions?: number
      drives?: number
      telemetry?: number
      music?: number
      fsd?: number
      sentry?: number
    }
    hidden?: {
      caity?: ("location" | "photos" | "charging" | "music" | "driving" | "speeds")[]
      api?: ("location" | "photos" | "charging" | "music" | "driving" | "speeds")[]
    }
    maps?: {
      live?: boolean
      trail?: boolean
      timeline?: boolean
    }
    zones?: {
      home?: boolean
      work?: boolean
      radiusM?: number
    }
  }
}
PUT/v1/vehicles/:vehicleId/data-policy

Changes the data policy: a field set takes effect on every read at once (viewRulesFor), null puts it back to today's behaviour, absent keeps it; a retention set also queues the purge of what is past it. Audited (vehicle.settings_update, data_policy, the groups changed, never their values). The owner's alone; 409 once the car's period has ended.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • locationobject
  • retentionobject
  • hiddenobject
  • hidden.caity("location" | "driving" | "speeds" | "charging" | "music" | "photos")[]or null

    Up to 6 items.

  • hidden.api("location" | "driving" | "speeds" | "charging" | "music" | "photos")[]or null

    Up to 6 items.

  • mapsobject
  • maps.livebooleanor null
  • maps.trailbooleanor null
  • maps.timelinebooleanor null
  • zonesobject
  • zones.homebooleanor null
  • zones.workbooleanor null
  • zones.radiusMintegeror null

    100–2000.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/data-policy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "location": {},
    "retention": {},
    "hidden": {
      "caity": [
        "location"
      ],
      "api": [
        "location"
      ]
    }
  }'
Send it from this page with your session or a key.

Response 200

{
  policy: {
    location?: {
      org?: "hidden" | "exact" | "approximate"
      maps?: "hidden" | "exact" | "approximate"
      you?: "hidden" | "exact" | "approximate"
    }
    retention?: {
      photos?: number
      charging?: number
      positions?: number
      drives?: number
      telemetry?: number
      music?: number
      fsd?: number
      sentry?: number
    }
    hidden?: {
      caity?: ("location" | "photos" | "charging" | "music" | "driving" | "speeds")[]
      api?: ("location" | "photos" | "charging" | "music" | "driving" | "speeds")[]
    }
    maps?: {
      live?: boolean
      trail?: boolean
      timeline?: boolean
    }
    zones?: {
      home?: boolean
      work?: boolean
      radiusM?: number
    }
  }
}
POST/v1/vehicles/:vehicleId/data/:class/delete

Deletes one class of the car's data for good (drives, positions, charging, telemetry, music, FSD, photos, Sentry): queued for the worker, which deletes everything of the class recorded so far (data-purge.ts); reads leave nothing of it out meanwhile, as it goes. The owner's, and only a person signed in (not a key, Caity or the phone assistant): 202 { queued: class }. Audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • class

    A kind of a car's data: positions, drives, charging, telemetry, music, fsd, photos or sentry (its data controls).

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/data/{class}/delete' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  queued: "photos" | "charging" | "positions" | "drives" | "telemetry" | "music" | "fsd" | "sentry"
}
PUT/v1/vehicles/:vehicleId/trips/:tripId/privacy

Who a drive is hidden from, and whose sight of its speeds: * or people and circles (empty: nobody). The owner's alone.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Request body

  • hiddenFromstring[]

    Up to 20 items. Each up to 140 characters.

  • speedHiddenFromstring[]

    Up to 20 items. Each up to 140 characters.

Also checked: Unknown fields are rejected. Say who it is hidden from, or whose speeds.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/privacy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "hiddenFrom": [
      "example"
    ],
    "speedHiddenFrom": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  tripId: string
  hiddenFrom: string[]
  speedHiddenFrom: string[]
}
PUT/v1/vehicles/:vehicleId/charges/:chargeId/privacy

Who a charge is hidden from: * or people and circles (empty: nobody). The owner's alone.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • chargeId

    A charge's id (chg_…), as the charges list gives it.

Request body

  • hiddenFromstring[]required

    Up to 20 items. Each up to 140 characters.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400Not a charge id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Not found
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/charges/{chargeId}/privacy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "hiddenFrom": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  chargeId: string
  hiddenFrom: string[]
}
GET/v1/vehicles/:vehicleId/trips/:tripId/links

A drive's share links: each one's linkId, when it was made and ends, and whether it hides the ends or the speeds. Needs share on the car and the drive shown to you; never the secret.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  links: {
    hideEnds: boolean
    hideSpeed: boolean
    photos?: boolean
    linkId: string
    url?: string
    createdAt: string
    expiresAt?: string
  }[]
}
POST/v1/vehicles/:vehicleId/trips/:tripId/links

→ 201 { linkId, url, createdAt, expiresAt, hideEnds, hideSpeed }: anyone with url sees the drive until it ends or is revoked. 403 privacy while the car's privacy hides the drive from anybody (or pauses it); hideSpeed is true whatever was asked while it hides the speeds, or the maker doesn't see them.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Request body

  • hideEndsboolean

    Default true.

  • hideSpeedboolean

    Default false.

  • photosboolean

    Default false.

  • daysinteger

    Default 7. 1–30.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "hideEnds": true,
    "hideSpeed": false,
    "photos": false
  }'
Send it from this page with your session or a key.

Response 201

{
  hideEnds: boolean
  hideSpeed: boolean
  photos?: boolean
  linkId: string
  url?: string
  createdAt: string
  expiresAt?: string
}
DELETE/v1/vehicles/:vehicleId/trips/:tripId/links/:linkId

Revokes a drive's share link at once: anyone opening it gets the same 404 as for a link that never was.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

  • linkId

    Link id (ilk_… for issue links, irl_… for remote links, plk_… for Photos links, lnk_… for sharing links and a drive's share links: not the link's secret).

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 400Not a link id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/links/{linkId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/charge-plan

Smart Charging: the cheapest start that has the car at its limit by readyBy (the tariff zone's clock, 07:00 by default).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • readyBystring

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/charge-plan' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  currency: string
  timeZone: string
  tariff?: {
    tariffId: string
    name?: string
    kind: "flat" | "tou"
  }
  battery?: {
    soc?: number
    limitPct?: number
    plugged?: boolean
    charging?: boolean
  }
  capacityKwh?: number
  kw: number
  kwFrom: "default" | "history"
  needKwh?: number
  readyBy: string
  readyAt: number
  best?: {
    start: number
    end: number
    cents: number
  }
  now?: {
    start: number
    end: number
    cents: number
  }
  savedCents?: number
  rates: {
    from: number
    to: number
    tenths: number
    period: "flat" | "peak" | "shoulder" | "offpeak"
  }[]
  schedule?: {
    startMinutes: number
    daysOfWeek: "All"
  }
  apply?: {
    lat: number
    lon: number
  }
  reason?: "full" | "no_rate" | "no_tariff" | "no_battery" | "no_capacity" | "too_late"
}
POST/v1/vehicles/:vehicleId/trip-plan

The trip planner: a plan to to (view; the car's use with trips, prices with costs, the car as the start with location). At most vehicles.trip.plansPerDay a person a day; a POST so a page coming back into view doesn't plan again.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • toobject
  • to.latnumberrequired

    -90–90.

  • to.lonnumberrequired

    -180–180.

  • to.namestring

    1–120 characters. Trimmed.

  • fromobject
  • from.latnumberrequired

    -90–90.

  • from.lonnumberrequired

    -180–180.

  • startSocinteger

    1–100.

  • reservePctinteger

    0–30.

  • chargeToPctinteger

    50–100.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
  • 503Routes can't be planned right now. Try again shortly.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trip-plan' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": {
      "lat": 1,
      "lon": 1
    },
    "from": {
      "lat": 1,
      "lon": 1
    },
    "startSoc": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  reason: "no_route" | "no_battery" | "no_start"
} | {
  route: {
    distanceKm: number
    durationMin: number
    points: [number, number][]
    chunks: {
      km: number
      kmh: number
    }[]
    roads: {
      atKm: number
      name: string
    }[]
  }
  energyKwh: number
  whPerKm: number
  temperatureFactor: number
  arriveSoc: number
  stops: {
    atKm: number
    point: {
      lat: number
      lon: number
    }
    road?: string
    charger?: {
      name: string
      availableStalls?: number
      totalStalls?: number
    }
    arriveSoc: number
    chargeToSoc: number
    kwh: number
    minutes: number
    cents: number
  }[]
  chargingMinutes: number
  stopsCents: number
  fromStartKwh: number
  tooFar?: true
  reason?: undefined
  from: {
    lat: number
    lon: number
    car?: true
    approximate?: true
  }
  to: {
    lat: number
    lon: number
    name?: string
  }
  startSoc: number
  startFrom: "car" | "given"
  reservePct: number
  chargeToPct: number
  capacityKwh: number
  capacityFrom: "car" | "charges" | "typical"
  energy: {
    from: "drives" | "typical"
    whPerKm: number
    drives: number
  }
  outsideC?: number
  dc: {
    kw: number
    kwFrom: "charges" | "typical"
    centsPerKwh: number
    priceFrom: "charges" | "typical"
  }
  currency: string
  homeCents?: number
  chargers: {
    state: "listed"
    superchargers: {
      lat: number
      lon: number
      name: string
      distanceKm: number
      availableStalls?: number
      totalStalls?: number
      closed?: boolean
    }[]
  } | {
    state: "unavailable" | "asleep" | "not_at_car" | "not_needed"
  }
  cached?: true
}
GET/v1/vehicles/:vehicleId/trip-plan/places

Places to plan a trip to, named like q (2 to 100 characters): saved places first, then Mapbox's.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • qstringrequired

    2–100 characters. Trimmed.

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trip-plan/places?q=example' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  places: {
    lat: number
    lon: number
    name: string
    detail?: string
    saved?: true
  }[]
  unavailable?: true
}
GET/v1/vehicles/:vehicleId/drain

Parked Drain: what the parked car loses and why (trips, for a caller who sees every drive); 90 days by default, a year at most.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 366 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/drain?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  hidden?: true
  from?: string
  to?: string
  truncated?: boolean
  periods?: number
  hours?: number
  kwhLost?: number
  kwhPerDay?: number
  centsPerKwh?: number
  centsPerDay?: number
  causes?: {
    cause: "sentry" | "climate" | "asleep" | "awake"
    hours: number
    kwh: number
    share: number
    kwhPerDay: number
    centsPerDay?: number
  }[]
  rates?: {
    sentry: number
    climate: number
    asleep: number
    awake: number
  }
}
GET/v1/vehicles/:vehicleId/savings

Savings: petrol and CO₂ against a petrol car, by month, from the drives the caller sees (trips); money with costs and a fuel price.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 1096 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/savings?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  truncated?: boolean
  periods: {
    distanceKm: number
    energyKwh: number
    petrolL: number
    petrolCo2Kg: number
    electricCo2Kg: number
    savedCo2Kg: number
    fuelCents?: number
    costCents?: number
    savedCents?: number
    start: string
  }[]
  total: {
    distanceKm: number
    energyKwh: number
    petrolL: number
    petrolCo2Kg: number
    electricCo2Kg: number
    savedCo2Kg: number
    fuelCents?: number
    costCents?: number
    savedCents?: number
  }
  from?: string
  to?: string
  timeZone: string
  currency: string
  factors: {
    petrolLPer100Km: number
    petrolFrom: "space" | "typical"
    petrolGPerL: number
    gridGPerKwh: number
    chargingLossPct: number
  }
}
GET/v1/vehicles/:vehicleId/review

The car's Year in Review for from to to (at most 400 days; a year back from to without from): distance, drives, time, charging, energy, the longest drive, busiest day, most efficient drive, climb, months and the places drives ended at most, from the drives and charges you see; costs and savings only with costs.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/review?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  from: string
  to: string
  timeZone?: string
  drives: number
  distanceKm: number
  drivingMinutes: number
  energyKwh: number
  climbM: number
  assistedKm?: number
  assistedOfKm?: number
  charges: number
  kwhAdded: number
  fastKwh: number
  costCents?: number
  savedCents?: number
  co2SavedKg?: number
  longest?: {
    tripId?: string
    startedAt: string
    distanceKm: number
    from?: string
    to?: string
    whPerKm?: number
  }
  busiestDay?: {
    day: string
    distanceKm: number
    drives: number
  }
  efficiencyBest?: {
    tripId?: string
    startedAt: string
    distanceKm: number
    from?: string
    to?: string
    whPerKm?: number
  }
  topSpeedKmh?: number
  cruise?: {
    kmh: number
    mph: number
  }
  places?: {
    name: string
    visits: number
  }[]
  months: {
    month: string
    distanceKm: number
    drives: number
  }[]
  music?: {
    minutes: number
    drivingMinutes: number
    drives: number
    artists: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    songs: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    stations: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    sources: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
  }
  truncated?: true
}
GET/v1/vehicles/:vehicleId/music

The music on the drives the caller sees, over a range as the review's (trips; hidden without the owner's say-so).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/music?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  from: string
  to: string
  hidden?: true
  music?: {
    minutes: number
    drivingMinutes: number
    drives: number
    artists: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    songs: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    stations: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
    sources: {
      name: string
      detail?: string
      minutes: number
      plays: number
    }[]
  }
  truncated?: true
}
GET/v1/vehicles/:vehicleId/review/links

The car owner's Year in Review links: each one's address, range, end and whether it shows costs and place names, and whether a link may go out now (linkable).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/review/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  links: {
    linkId: string
    url?: string
    createdAt: string
    expiresAt?: string
    from: string
    to: string
    money: boolean
    places: boolean
    speeds: boolean
    music: boolean
    photos?: boolean
  }[]
  linkable: boolean
  placeNames: boolean
  speeds: boolean
  music: boolean
}
POST/v1/vehicles/:vehicleId/review/links

→ 201 { linkId, url, createdAt, expiresAt, from, to, money, places, speeds, music }: anyone with url sees the range's review until the link ends or is revoked. 403 privacy while the car shows its drives to nobody or sharing is paused; places is false whatever was asked while the car hides place names, speeds (off unless asked for) while it hides speeds on drives, and music (off unless asked for) while it hides music.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • fromstringrequired

    Up to 40 characters.

  • tostringrequired

    Up to 40 characters.

  • daysinteger

    Default 30. 1–90.

  • moneyboolean

    Default false.

  • placesboolean

    Default false.

  • speedsboolean

    Default false.

  • musicboolean

    Default false.

  • photosboolean

    Default false.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/review/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "example",
    "to": "example"
  }'
Send it from this page with your session or a key.

Response 201

{
  linkId: string
  url?: string
  createdAt: string
  expiresAt?: string
  from: string
  to: string
  money: boolean
  places: boolean
  speeds: boolean
  music: boolean
  photos?: boolean
}
DELETE/v1/vehicles/:vehicleId/review/links/:linkId

Ends a Year in Review link at once: anyone opening it gets the same 404 as for a link that never was.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • linkId

    Link id (ilk_… for issue links, irl_… for remote links, plk_… for Photos links, lnk_… for sharing links and a drive's share links: not the link's secret).

Errors

  • 400Not a vehicle id.
  • 400Not a link id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/review/links/{linkId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/speed

The car's speeds for from to to (its whole history without from), from the drives whose speed you see with a speed summary by the current rules: the top speed and its drive, the cruising speed, the fastest speed held for 30 seconds, a minute, five and ten, the distance at each whole km/h of sustained cruising and of all moving time with their percentiles and bands, the five fastest drives, and how many drives were counted, imported, hidden or have no speeds yet. Needs trips.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/speed?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  from: string
  to: string
  timeZone?: string
  drives: number
  hidden: number
  pending: number
  counted: number
  approx: number
  top?: {
    tripId: string
    startedAt: string
    approx?: true
    kmh: number
  }
  cruise?: {
    kmh: number
    mph: number
  }
  held: {
    tripId: string
    startedAt: string
    approx?: true
    windowS: number
    kmh: number
  }[]
  cruising?: {
    km: number
    hours: number
    byKmh: {
      [key: string]: number
    }
    percentiles: {
      p: number
      kmh: number
    }[]
    bands: {
      kmh: {
        from?: number
        to?: number
        km: number
        share: number
      }[]
      mph: {
        from?: number
        to?: number
        km: number
        share: number
      }[]
    }
  }
  moving?: {
    km: number
    hours: number
    byKmh: {
      [key: string]: number
    }
    percentiles: {
      p: number
      kmh: number
    }[]
    bands: {
      kmh: {
        from?: number
        to?: number
        km: number
        share: number
      }[]
      mph: {
        from?: number
        to?: number
        km: number
        share: number
      }[]
    }
  }
  fastest: {
    tripId: string
    startedAt: string
    approx?: true
    kmh: number
    distanceKm?: number
  }[]
  truncated?: true
}
GET/v1/vehicles/:vehicleId/appearance

Appearance's choices (?base=<ruleId> for another body): the car's choice (choice, or null: automatic), every body the rows draw, and the chosen body's paints, wheels and interiors, each with the configurator's picture of it on that body, signed on our CDN. The worker fetches pictures not yet in the bucket (the API never calls Tesla), within the fetch limit: complete false when some are still to come. In the Tesla rate group, as it can reach Tesla's compositor.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • basestring

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
  • 503Car pictures aren't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/appearance' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  bases: {
    picture?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
    approximate?: boolean
    ruleId: string
    label: string
  }[]
  paint: {
    picture?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
    approximate?: boolean
    ruleId: string
    label: string
  }[]
  wheels: {
    picture?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
    approximate?: boolean
    ruleId: string
    label: string
  }[]
  interior: {
    picture?: {
      srcset: {
        url: string
        width: number
        height: number
      }[]
      box: {
        x: number
        y: number
        w: number
        h: number
      }
    }
    approximate?: boolean
    ruleId: string
    label: string
  }[]
  complete: boolean
  base?: string
  choice: null | {
    base: string
  }
  photo: boolean
  enabled: boolean
}
PUT/v1/vehicles/:vehicleId/appearance

Chooses the car's appearance: a base row and, optionally, a paint, wheels and interior row of its car type (any the rows hold, enabled or not). 400 when a row is gone or doesn't fit the base. Turns the picture on (pictureMode tesla), queues the resolve, and is audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • basestringrequired

    Matches ^[a-z0-9][a-z0-9_-]{1,79}$.

  • paintstring

    Matches ^[a-z0-9][a-z0-9_-]{1,79}$.

  • wheelsstring

    Matches ^[a-z0-9][a-z0-9_-]{1,79}$.

  • interiorstring

    Matches ^[a-z0-9][a-z0-9_-]{1,79}$.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 400That appearance isn't one the pictures can draw: a choice is gone or doesn't fit the model.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
  • 503Car pictures aren't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/appearance' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "base": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  choice: null | {
    base: string
  }
}
POST/v1/vehicles/:vehicleId/photo/uploads

Starts a photo of the car: { type, size } of the picture the app has already cropped to the car. A presigned PUT, its type and length signed, to up/<uploadId> in the pictures bucket for 15 minutes; the upload is the caller's, for this car, and is checked when it is finished. Within the photo size limit (vehicles.pictures.photoKb, Admin → Limits).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • typeanyrequired
  • sizeintegerrequired

    > 0.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
  • 413A photo can be at most … KB. Crop it smaller.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/photo/uploads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "example",
    "size": 1
  }'
Send it from this page with your session or a key.

Response 201

{
  uploadId: string
  url: string
  headers: {
    "content-type": "image/png" | "image/jpeg" | "image/webp"
  }
  expiresAt: string
}
PUT/v1/vehicles/:vehicleId/photo

Finishes a photo: the upload must be the caller's for this car. The worker checks it (the size and type it declared, read from its first bytes; a picture of a car's crop's size and shape), removes its location and camera details and keeps it as c/<photoId>.<ext> (a new random id), deleting the upload either way. It goes on both rows with the picture on; any earlier photo is queued for the worker to delete. Audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Request body

  • uploadIdstringrequired

    Matches ^[0-9a-f]{32}$.

Also checked: Unknown fields are rejected.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404That upload isn't here. Send the photo again.
  • 409This car's period has ended.
  • 409This car's picture changed meanwhile. Try again.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/photo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "uploadId": "<uploadId>"
  }'
Send it from this page with your session or a key.

Response 200

{
  photo: {
    width: number
    height: number
  }
}
DELETE/v1/vehicles/:vehicleId/photo

Takes the photo off: the next picture by precedence shows, and the worker deletes its file. Audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 409This car's period has ended.
  • 409This car's picture changed meanwhile. Try again.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/photo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photo: null
}
DELETE/v1/vehicles/:vehicleId/appearance

Back to automatic: the appearance goes, and the configuration's picture shows again (a photo still wins). Audited.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Errors

  • 400Not a vehicle id.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
  • 404Vehicle not found
  • 409This car's period has ended.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/appearance' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  choice: null
}
GET/v1/vehicles/:vehicleId/trips/:tripId/media

A drive's photos and videos: your own on it, others' only where their owners show them (without names or places), and, on your own car, suggestions from your Photos library unless you turned them off, best first, each with its confidence and why (notice the first time). Needs trips and the drive shown to you; a person signed in, never a key.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  media: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  suggestions: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  canAdd: boolean
  suggest?: boolean
  notice?: boolean
  shared: boolean
}
GET/v1/vehicles/:vehicleId/trips/:tripId/media/candidates

Your Photos library 12 hours either side of the drive, newest first, each saying whether it's on the drive and whether it was taken during it or at its stop: what Add Photos offers.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media/candidates' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    width?: number
    height?: number
    duration?: number
    onDrive: boolean
    during: boolean
  }[]
  from: string
  to: string
}
POST/v1/vehicles/:vehicleId/trips/:tripId/media

Puts photos from your own library on the drive (photoIds, up to 50; 200 a drive): references, the files stay in Photos. 404 when none of them is yours.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Request body

  • photoIdsstring[]required

    1–50 items. Each matches ^[a-z]{2,8}_[0-9A-Za-z]{8,40}$.

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "photoIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  media: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  suggestions: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  canAdd: boolean
  suggest?: boolean
  notice?: boolean
  shared: boolean
}
PUT/v1/vehicles/:vehicleId/trips/:tripId/media/sharing

Whether your photos on the drive show to the people who can see it (shared); photos you add later follow it.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

Request body

  • sharedbooleanrequired

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media/sharing' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "shared": true
  }'
Send it from this page with your session or a key.

Response 200

{
  shared: boolean
  count: number
}
PUT/v1/vehicles/:vehicleId/trips/:tripId/media/:photoId

Adds a suggested photo to the drive or dismisses it (status: accepted or dismissed); a dismissed photo isn't suggested for the drive again.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Request body

  • status"accepted" | "dismissed"required

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 400Not a photo id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X PUT 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "accepted"
  }'
Send it from this page with your session or a key.

Response 200

{
  media: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  suggestions: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    duration?: number
    mine: boolean
    status: "accepted" | "suggested"
    source?: "match" | "manual"
    confidence?: number
    match?: {
      where: "stop" | "before" | "during"
      distanceM?: number
    }
    location?: {
      lat: number
      lon: number
    }
  }[]
  canAdd: boolean
  suggest?: boolean
  notice?: boolean
  shared: boolean
}
DELETE/v1/vehicles/:vehicleId/trips/:tripId/media/:photoId

Takes your photo off the drive; it stays in your library.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

  • tripId

    A drive's id (drv_…), as the drives list gives it.

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Errors

  • 400Not a vehicle id.
  • 400Not a drive id.
  • 400Not a photo id.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl -X DELETE 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/trips/{tripId}/media/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/vehicles/:vehicleId/media

The drives that started from from to to (at most 400 days) with photos you may see: how many, how many of yours wait for review, and the first few: the drive list's covers and Activity's day.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 400 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/media?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  drives: {
    tripId: string
    startedAt: string
    count: number
    review: number
    photos: {
      photoId: string
      kind: "raw" | "video" | "live" | "photo"
      takenAt: string
      thumbUrl?: string
      mine: boolean
    }[]
  }[]
}
GET/v1/vehicles/:vehicleId/review/media

A Year in Review's photos for from to to: up to nine of those you may see, spread across the range, one a drive before a second from any.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vehicleId

    A vehicle's id (veh_…): one owner's period with one VIN. Another owner of the same car has another id.

Query parameters

  • fromany JSONrequired
  • toany JSONrequired

Errors

  • 400Not a vehicle id.
  • 400Ask for at most 400 days at a time.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/vehicles/{vehicleId}/review/media?from=%7B%7D&to=%7B%7D' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    takenAt: string
    thumbUrl?: string
    previewUrl?: string
    width?: number
    height?: number
    cardUrl?: string
  }[]
}
GET/v1/me/widgets/vehicle

The Vehicle widget's numbers for a car the person holds view on: state, state of charge, range, charging, locks and cabin temperature; no position. People only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • vehicleIdstringrequired

    Up to 60 characters.

Errors

  • 400Not a vehicle id.
  • 403Widgets belong to people.
  • 403Widgets are read by the app.
  • 403Vehicles isn't available to the phone assistant.
  • 403Vehicles is reachable from the Vehicles and phone apps.
  • 403Vehicles needs a key made by a person.
  • 404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/me/widgets/vehicle?vehicleId=%3CvehicleId%3E' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  vehicleId: string
  name: string
  ended: {
    at?: string
  }
}
| {
  vehicleId: string
  name: string
  state?: "offline" | "charging" | "online" | "parked" | "driving" | "asleep"
  lastSeen?: string
  soc?: number
  rangeKm?: number
  plugged?: boolean
  chargeKw?: number
  chargeLimitPct?: number
  etaMin?: number
  locked?: boolean
  insideC?: number
}