API reference
Maps and flight watches
Live aircraft, flight history, saved maps and places, flight watches, notification groups, web push, and Find My.
GET
/An event's public position page (the link texts and emails give recipients outside the platform): the event's title, time, time zone and position, and until when the page follows the aircraft. No authentication; no watch, organization or recipient details. 410 once the link has expired (7 days).
- Auth
- None.
Path parameters
tokenA 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.
curl 'https://api.cactive.com.au/v1/hooks/maps/p/{token}'Send it from this page with your session or a key.
Response 200
{
label: string
at: number
timeZone: string
lat: number
lon: number
lost: boolean
liveUntil: number
live: boolean
expiresAt: number
}GET
/Where that event's aircraft is now (position, altitude, speed, track), from the live picture, for 2 hours after the event: aircraft is null while it isn't seen, live: false after that. Only that one aircraft. No authentication; rate-limited per link.
- Auth
- None.
Path parameters
tokenA 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.
curl 'https://api.cactive.com.au/v1/hooks/maps/p/{token}/live'Send it from this page with your session or a key.
Response 200
{
live: false
aircraft: null
} | {
live: true
aircraft: null
} | {
live: true
aircraft: {
at: number
lat: number
lon: number
alt: null | number
gs: null | number
track: null | number
onGround: boolean
icon: "unknown" | "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone" | "ground"
}
}POST
/A shared trip's link (docs/maps/directions.md → A link for someone without an account): { token } in the body, so the token stays out of request lines and logs. The trip as someone it's shared with sees it, the sharer's name alone; 404 for anything a link doesn't open; 429 with Retry-After past maps.eta.linkOpensPerHour from one address.
- Auth
- None.
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/hooks/maps/eta-link'Send it from this page with your session or a key.
Response 200
{
status: "active" | "stopped" | "arrived"
startedAt: null | number
mode: null | "drive" | "walk" | "cycle"
endedAt: null | number
to: null | {
lat: number
lon: number
name?: string
personId?: string
}
heading: null | string
endsAt: number
etaAt: null | number
remainingM: null | number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
from: {
name: string
}
}GET
/A notification recipient's status (pending, active, unsubscribed) and group name. No authentication: the token is the recipient's own.
- Auth
- None.
Path parameters
tokenA 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.
curl 'https://api.cactive.com.au/v1/hooks/maps/notify/{token}'Send it from this page with your session or a key.
Response 200
{
status: "active" | "pending" | "unsubscribed"
group: string
email?: string
phone?: string
}POST
/Confirms a recipient (double opt-in). No authentication.
- Auth
- None.
Path parameters
tokenA 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.
curl -X POST 'https://api.cactive.com.au/v1/hooks/maps/notify/{token}/confirm'Send it from this page with your session or a key.
Response 200
{
status: "active" | "pending" | "unsubscribed"
group: string
email?: string
phone?: string
}POST
/Unsubscribes a recipient (RFC 8058 one-click: mail clients post here from the List-Unsubscribe header). No authentication.
- Auth
- None.
Path parameters
tokenA 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.
curl -X POST 'https://api.cactive.com.au/v1/hooks/maps/notify/{token}/unsubscribe'Send it from this page with your session or a key.
Response 200
{
status: "active" | "pending" | "unsubscribed"
group: string
email?: string
phone?: string
}POST
/A background location report from the Maps app with the phone's key (Authorization: Bearer si_loc_…; the body as for …/report). The key writes only its phone's fix and works only while that phone's sign-in does: 401 otherwise, and the phone's location is deleted. 204 when dropped (one report per 20 s is stored).
- Auth
- None.
Errors
400Send JSON.401Unauthorized
curl -X POST 'https://api.cactive.com.au/v1/hooks/maps/location'Send it from this page with your session or a key.
Response 200
{
ok: true
validUntil?: number
}Response 204 with no body
GET
/{ cars }: the cars you see, where you may see them (Vehicles' sharing rules), with their state, battery and picture. Empty where Vehicles isn't available.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/cars' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
cars: {
vehicleId: string
name: string
model?: string
owned: boolean
ownerSpace: string
state?: string
soc?: number
lastSeen?: number
position?: {
lat: number
lon: number
accuracyM?: number
approximate?: true
headingDeg?: number
place?: string
at?: number
}
precision: "hidden" | "exact" | "approximate"
capabilities: string[]
offline: boolean
watches: {
leftBehind: boolean
found: boolean
}
colour?: string
art?: string
picture?: {
views: {
"3qtr"?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
side?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
}
approximate?: true
source: string
}
}[]
}POST
/Where the cars you see have been (docs/maps/timeline.md → Trails): each car's drive so far, or its last drive when it parked recently, as Vehicles shows it to you; null for a car with nothing to show (whatever the reason). Each ask says what you hold, so the answer has only what's new.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Request body
carsobject[]required1–10 items.
cars[].vehicleIdstringrequiredMatches
^veh_[0-9a-z]{8,40}$.cars[].tripIdstringMatches
^drv_[0-9a-z]{8,40}$.cars[].sinceinteger≥ 0.
cars[].stretchinteger0–1000.
cars[].roadbooleancars[].doneboolean
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/cars/trails' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"cars": [
{
"vehicleId": "<vehicleId>"
}
]
}'Send it from this page with your session or a key.
Response 200
{
trails: {
[key: string]: null
}
}
| {
trails: {
[key: string]: null | {
tripId: string
open: boolean
startedAt: number
endedAt?: number
points: [number, number, number][]
through?: number
replace?: true
stretches?: {
from: number
lines: (null | {
road: boolean
points: object
from: number
to: number
t?: object
}[])[]
}
road?: null | {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
roadPending?: true
} | {
keep: true
}
}
}GET
/One page of what happened between from and to (ISO dates or epoch milliseconds, at most 31 days): { range, items, sources, next?, keeps }. sources (vehicles, flights, people; all by default) picks what is read. next.to asks for the earlier part.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Errors
400Give from and to (ISO dates or epoch milliseconds).403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/timeline' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
range: {
from: number
to: number
}
items: {
id: string
source: "events" | "photos" | "vehicles" | "people" | "flights"
kind: "drive" | "photos" | "event" | "charge" | "trail" | "flight" | "parked" | "flight_event" | "visit"
at: number
end?: number
title: string
detail?: string
line?: [number, number][]
times?: number[]
road?: {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
roadPending?: true
point?: [number, number]
timed?: boolean
subject?: string
ref: {
vehicleId?: string
tripId?: string
chargeId?: string
idleId?: string
watchId?: string
flightId?: string
deviceId?: string
photoId?: string
orgSlug?: string
mailboxId?: string
calendarId?: string
eventId?: string
date?: string
}
count?: number
placesHidden?: true
distanceKm?: number
}[]
sources: {
events?: "ok" | "none" | "off"
photos?: "ok" | "none" | "off"
vehicles?: "ok" | "none" | "off"
people?: "ok" | "none" | "off"
flights?: "ok" | "none" | "off"
}
next?: {
to: number
}
keeps: {
trailHours: number
}
}GET
/{ layers: { photos, events, traffic, tasks } }: which of the map's other layers you may turn on here (docs/maps/layers.md): scopes and the org's app switches.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Errors
403This is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/layers' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
layers: {
events: boolean
photos: boolean
tasks: boolean
traffic: boolean
}
}GET
/A photo's card on the map: { photo: { photoId, kind, takenAt, thumbUrl? } }, for one of your own located photos.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).photoIdPhoto id: the photo's file in Drive (
fil_…).
Errors
403This is yours: open it in the Maps app.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:read404Photo not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/layers/photos/{photoId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
photo: {
thumbUrl?: string
photoId: string
kind: "raw" | "video" | "live" | "photo"
takenAt: number
}
}GET
/A layer's things (LayerAnswer): photos (your own, in bbox), events (your events from yesterday to a month ahead, at their places), traffic (your organisation's Cloud traffic by country, the last 7 days) or tasks (your organisation's Tasks issues with a place in bbox, as you can open them in Tasks; spaces (keys) and status (todo, inprogress, done) filter them, open work by default). bbox is west,south,east,north; the answer's box says what it covers (everywhere for events and traffic). state: "off" where it isn't yours to see here.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).layerOne of the map's other layers:
photos(your own),events(your calendar events at their places) ortraffic(your organisation's Cloud traffic by country).
Query parameters
bboxstringspacesstringstatusstring
Errors
400Give bbox as west,south,east,north in degrees.403This is yours: open it in the Maps app.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:read404No such layer.404Serverless App Service not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/layers/{layer}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
layer: "events" | "photos" | "tasks" | "traffic"
box: [number, number, number, number]
items: {
id: string
layer: "events" | "photos" | "tasks" | "traffic"
lat: number
lon: number
title: string
at?: number
end?: number
allDay?: boolean
detail?: string
status?: string
space?: string
category?: "done" | "todo" | "inprogress"
weight?: number
kind?: "video" | "photo"
ref: {
photoId?: string
orgId?: string
orgSlug?: string
mailboxId?: string
calendarId?: string
eventId?: string
calendar?: string
date?: string
country?: string
issueKey?: string
}
}[]
state: "ok" | "off"
truncated?: true
unplaced?: number
total?: number
filter?: string
spaces?: {
key: string
name: string
}[]
}GET
/A drive on the timeline with its track, for playback: as Vehicles' drive detail answers it, for a drive you see.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
400Not a drive.403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.404Drive not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/timeline/drives/{vehicleId}/{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
}[]
}
}POST
/Drives' lines on the roads they took ({ drives: [{ vehicleId, tripId }] }, up to 50): { roads: { [tripId]: stretches | "pending" | null } }. Display only.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Request body
drivesobject[]required1–50 items.
drives[].vehicleIdstringrequiredMatches
^veh_[0-9a-z]{8,40}$.drives[].tripIdstringrequiredMatches
^drv_[0-9a-z]{8,40}$.
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/timeline/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"drives": [
{
"vehicleId": "<vehicleId>",
"tripId": "<tripId>"
}
]
}'Send it from this page with your session or a key.
Response 200
{
roads: {}
}
| {
roads: {
[key: string]: null | "pending" | {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
}
}POST
/Directions (docs/maps/directions.md): { from, to, mode } (drive with live traffic, walk, cycle) answers { routes } (the best and up to two alternatives, with steps; a drive's traffic) or { error: "no_route" | "too_far" | "unavailable" }. POST, so the points stay out of URLs and logs; they go to Mapbox for this request only. Counted per person per hour (maps.directions.routesPerHour): past it, 429 with Retry-After.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Request body
fromobjectrequiredfrom.latnumberrequired-90–90.
from.lonnumberrequired-180–180.
toobjectrequiredto.latnumberrequired-90–90.
to.lonnumberrequired-180–180.
mode"drive" | "walk" | "cycle"required
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/directions' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"from": {
"lat": 1,
"lon": 1
},
"to": {
"lat": 1,
"lon": 1
},
"mode": "drive"
}'Send it from this page with your session or a key.
Response 200
{
routes?: {
distanceM: number
durationS: number
typicalS?: number
name: string
line: [number, number][]
congestion: {
from: number
to: number
level: "heavy" | "moderate" | "severe"
}[]
steps: {
instruction: string
distanceM: number
durationS: number
maneuver: {
type: string
modifier?: string
}
at: [number, number]
road?: string
}[]
}[]
error?: "unavailable" | "no_route" | "too_far"
}GET
/{ on, available }: whether you draw drives on the roads they took (on unless you turned it off), and whether there are drives here.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Errors
403This is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
on: boolean
available: boolean
}PUT
/Draws drives on the roads they took, or as driven ({ on }): your choice, shared with Vehicles' Display.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Request body
onbooleanrequired
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read409There are no drives to draw here.
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"on": true
}'Send it from this page with your session or a key.
Response 200
{
on: boolean
}GET
/What the apps need to draw: the ADS-B source and its credit line, preset areas, event types, channels (mobile, web, email, sms, call: available or not, and their labels), what a new watch gets by default for the caller (defaults: events, channels, smsEvents), the Mapbox public token for the native map with the Referer it may need (mapbox), and for texts whether the SMS account is still in the provider's sandbox and where the caller's own texts go (masked). For circling and approach alerts: aircraft classes, enabled aircraft presets, the org's locations, circling sensitivity presets and approach defaults. units: the caller's units for measurements (the org's setting with their own on top; /settings).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/config' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
provider: {
id: string
label: string
attribution: string
terms: string
lookups: {
registration: boolean
callsign: boolean
type: boolean
hexBatch: number
}
}
providers: ["adsblol", "adsbfi", "airplaneslive", "opensky", "adsbexchange"]
sources: {
id: string
label: string
attribution: string
use: "all" | "last_resort"
}[]
areas: {
id: string
label: string
source: string
}[]
events: {
needsPoint?: true
type: "emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead"
label: string
}[]
aircraftClasses: {
id: "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone"
label: string
}[]
presets: [] | {
id: string
label: string
}[]
locations: {
locationId: string
name: string
lat: number
lon: number
siteRadiusM: number
}[]
circling: {
sensitive: {
turns: 0.75
radiusKm: 3
windowMinutes: 10
}
normal: {
turns: 1
radiusKm: 2
windowMinutes: 8
}
strict: {
turns: 2
radiusKm: 1.5
windowMinutes: 8
}
}
approachDefaults: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
deliveryLabels: {
failed: string
sent: string
duplicate: string
quiet: string
cooldown: string
no_recipients: string
}
channels: {
mobile: true
web: true
email: boolean
sms: boolean
call: boolean
}
channelLabels: {
[key: string]: string
}
defaults: {
events: {
emergency: boolean
takeoff: boolean
landing: boolean
signal_lost: boolean
signal_resumed: boolean
area_enter: boolean
area_leave: boolean
orbit: boolean
road_follow: boolean
road_switch: boolean
road_repeat: boolean
road_leave: boolean
interchange: boolean
threshold: boolean
approach: boolean
overhead: boolean
}
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
mapbox: {
token: null | string
referer: null | string
}
sms: {
sandbox: boolean | null
phone: null | string
phoneSettings: null | string
}
units: {
speed: string
altitude: string
distance: string
}
}GET
/Maps settings: the units measurements show in (speed kt | km/h | mph, altitude ft | m, distance nm | km | mi). units is what the caller sees, org.units the org's setting and mine.units the caller's own (each only what it sets; unset is knots, feet, nautical miles).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/settings' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
units: {
speed: "kt" | "km/h" | "mph"
altitude: "m" | "ft"
distance: "nm" | "km" | "mi"
}
org: {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
mine: null | {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
canEditOrg: boolean
}PUT
/The org's units, for everyone without their own (org owners and admins, or a key, with maps:write). A unit left out goes back to the default.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/settings' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
units: {
speed: "kt" | "km/h" | "mph"
altitude: "m" | "ft"
distance: "nm" | "km" | "mi"
}
org: {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
mine: null | {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
canEditOrg: boolean
}PUT
/The caller's own units, in every org, over the org's ({ units: null } follows the org again). People only.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/settings/me' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
units: {
speed: "kt" | "km/h" | "mph"
altitude: "m" | "ft"
distance: "nm" | "km" | "mi"
}
org: {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
mine: null | {
units: {
speed?: "kt" | "km/h" | "mph"
altitude?: "m" | "ft"
distance?: "nm" | "km" | "mi"
}
}
canEditOrg: boolean
}GET
/Live aircraft inside bbox (west,south,east,north), from the flight poller's latest snapshot: position, barometric altitude (null on the ground), ground speed, track, vertical rate, callsign, registration, type, squawk, icon class and, with trails=1, the last 15 minutes of track. Also returns the source, its credit line and the areas polled. Views outside the polled areas are added to the poller's areas for a few minutes.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
bboxstringtrailsstring
Errors
400bbox is west,south,east,north in degrees.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/aircraft' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
issues?: string[]
pending: boolean
at: null
provider: null
coverage: []
aircraft: []
sources?: undefined
} | {
issues?: string[]
pending: boolean
at: number
provider: {
label: string
id: string
attribution: string
}
sources?: {
label: string
id: string
attribution: string
}[]
coverage: {
lat: number
lon: number
radiusNm: number
}[]
aircraft: {
type?: string
at: number
hex: string
source?: string
desc?: string
lat: number
lon: number
alt: null | number
onGround: boolean
altGeom?: number
gs?: number
track?: number
vs?: number
callsign?: string
registration?: string
category?: string
squawk?: string
emergency?: string
icon: "unknown" | "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone" | "ground"
operator?: string
road?: string
trail?: ([number, number, number, null | number, null | number, null | number])[]
}[]
}GET
/The nearest aircraft in the air to a point, and the next two (the phone's nearest-aircraft widget): which way each is from the point (bearingDeg, compass), how far (rangeM), its altitude (ft), speed (kt), track and phase, and, while it descends, when it should land (landing.at, unix seconds) and at which airport when one lies ahead on its track. The point is rounded to about 100 m and never stored or logged; like a map view, an area outside the polled ones is covered for a few minutes from now (pending until it is). units: the caller's Maps units, for showing the numbers.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
latnumberrequired-90–90. Coerced from a string.
lonnumberrequired-180–180. Coerced from a string.
radiusKmnumberDefault
50. 1–200. Coerced from a string.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/aircraft/nearest?lat=1&lon=1' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
units: {
speed: string
altitude: string
distance: string
}
radiusKm: number
aircraft: {
hex: string
callsign?: string
registration?: string
type?: string
desc?: string
operator?: string
icon: "unknown" | "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone" | "ground"
at: number
rangeM: number
bearingDeg: number
compass: "S" | "N" | "E" | "NE" | "SE" | "SW" | "W" | "NW"
alt: null | number
gs?: number
track?: number
vs?: number
phase: "lost" | "taxi" | "climbing" | "cruise" | "descending" | "landed"
landing: null | {
at: number
airport: null | {
name: string
code?: string
}
}
}[]
issues?: string[]
at: null | number
provider: null | {
label: string
id: string
attribution: string
}
sources?: {
label: string
id: string
attribution: string
}[]
pending: boolean
}GET
/Aircraft in the live snapshot by ICAO hex, registration or callsign (q; exact matches first, then prefixes).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
qstringDefault
"".
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/aircraft/search' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
aircraft: {
trail?: undefined
type?: string
at: number
hex: string
source?: string
desc?: string
lat: number
lon: number
alt: null | number
onGround: boolean
altGeom?: number
gs?: number
track?: number
vs?: number
callsign?: string
registration?: string
category?: string
squawk?: string
emergency?: string
icon: "unknown" | "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone" | "ground"
operator?: string
road?: string
}[]
}GET
/One aircraft wherever it is, with its recent track: live from the snapshot (live: true), else its last known position and the track before it from recorded positions (live: false, lastSeen), or aircraft: null when nothing is known. When it isn't live the poller looks it up by hex for a few minutes (pending).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).hexICAO 24-bit aircraft address, 6 hex digits (
7c6b2d).
Errors
404Aircraft not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/aircraft/{hex}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
at: null | number
provider: null | {
label: string
id: string
attribution: string
}
aircraft: null | {
type?: string
at: number
hex: string
source?: string
desc?: string
lat: number
lon: number
alt: null | number
onGround: boolean
altGeom?: number
gs?: number
track?: number
vs?: number
callsign?: string
registration?: string
category?: string
squawk?: string
emergency?: string
icon: "unknown" | "helicopter" | "heavy" | "jet" | "turboprop" | "light" | "glider" | "balloon" | "drone" | "ground"
operator?: string
road?: string
trail?: ([number, number, number, null | number, null | number, null | number])[]
}
live: boolean
lastSeen: null | number
pending?: boolean
}GET
/Recorded track of a watched aircraft over the last hours (0.25–24, default 6): points [seconds, lon, lat, altitude ft | null, ground speed kt, track°], oldest first. Positions are recorded only while a watch covers the aircraft (kept 14 days).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).hexICAO 24-bit aircraft address, 6 hex digits (
7c6b2d).
Query parameters
hoursstringDefault
6.
Errors
404Aircraft not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/aircraft/{hex}/track' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
points: ([number, number, number, null | number, null | number, null | number])[]
distanceNm: number
recorded: boolean
registration?: string
callsign?: string
type?: string
hex: string
from: number
to: number
}GET
/Saved maps the caller can see: their own, and those shared with the organization or by link. With places=1, each map includes its places.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
placesstring
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
lists: {
listId: string
orgId: string
ownerId: string
name: string
description?: string
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
sharing: "org" | "link" | "private"
shareToken?: string
placeCount: number
createdAt: number
updatedAt: number
places?: {
placeId: string
listId: string
name: string
note?: string
lat: number
lon: number
address?: string
color?: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon?: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
createdBy: string
createdAt: number
updatedAt: number
}[]
}[]
}POST
/Creates a saved map: name, optional description, pin color (chart-1…chart-5, foreground), icon and sharing (private, org, link).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
list: {
listId: string
orgId: string
ownerId: string
name: string
description?: string
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
sharing: "org" | "link" | "private"
shareToken?: string
placeCount: number
createdAt: number
updatedAt: number
}
}GET
/A saved map with its places.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
list: {
places: {
placeId: string
listId: string
name: string
note?: string
lat: number
lon: number
address?: string
color?: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon?: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
createdBy: string
createdAt: number
updatedAt: number
}[]
listId: string
orgId: string
ownerId: string
name: string
description?: string
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
sharing: "org" | "link" | "private"
shareToken?: string
placeCount: number
createdAt: number
updatedAt: number
}
}PATCH
/Renames a map or changes its description, pin style or sharing. sharing: "link" returns a shareToken for the public link; rotateLink: true replaces it; any other sharing turns the link off. Owner, or an org admin for shared maps.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
list: {
listId: string
orgId: string
ownerId: string
name: string
description?: string
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
sharing: "org" | "link" | "private"
shareToken?: string
placeCount: number
createdAt: number
updatedAt: number
}
}DELETE
/Deletes a map and its places.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}POST
/Adds a place: name, lat, lon, optional note, address, and its own pin color and icon.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}/places' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
place: {
placeId: string
listId: string
name: string
note?: string
lat: number
lon: number
address?: string
color?: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon?: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
createdBy: string
createdAt: number
updatedAt: number
}
}PATCH
/Changes a place; moveTo moves it to another of your maps.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).placeIdA place's id: in Maps a saved place (
plc_…), in Vehicles a space's charging place (vpl_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}/places/{placeId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
place: {
placeId: string
listId: string
name: string
note?: string
lat: number
lon: number
address?: string
color?: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
icon?: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
createdBy: string
createdAt: number
updatedAt: number
}
}DELETE
/Removes a place.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).listIdSaved map id (
mls_…); undermarketinga list (mkl_…); underme/fooda shopping list (fls_…).placeIdA place's id: in Maps a saved place (
plc_…), in Vehicles a space's charging place (vpl_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/lists/{listId}/places/{placeId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/Flight watches the caller can see (their own and those shared with the organization).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watches: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}[]
}POST
/Creates a flight watch: name, targets ({ kind: hex | registration | callsign | type, value }, a trailing * matches prefixes; no_callsign, any (value *) and class (helicopter, light, turboprop, jet, heavy, glider, balloon, drone) match inside areas only and need one; preset names an aircraft preset), exclude (the same shape: aircraft matching any never match, e.g. callsign POL3* except POL31), areas ({ kind: "preset", id: "au-vic" }, circles { center: [lon, lat], radiusKm }, polygons { ring: [[lon, lat], …] }, an org location { kind: "location", locationId, radiusKm } or { kind: "near_me", radiusKm } around the owner's phone, which makes the watch personal: private, the owner's only, no groups or people), limitToAreas, events (on/off per event type; approach and overhead need a location or near-me area), settings (signal, orbit with maxAltitudeFt, loiterMinutes and ignoreAirportsKm, approach, roads, thresholds), notify (channels: mobile, web, email, sms, call, with the older push read as mobile and web; includeOwner, groupIds, userIds (org members), smsEvents, smsFormat, smsPrefix, cooldownMinutes, timeZone, quietHours), identity (mode: any or pin_first; pinnedHex), lifetime (startsAt, endsAt or forHours, maxNotifications, maxFlights, schedule with days, start, end, timeZone) and log (enabled, retentionDays, null for forever). Type targets match inside the watch's areas. Left out, every event is on and channels are the caller's defaults (GET …/maps/config → defaults). The maker gets a confirmation by push when they're a recipient. See Maps → Flight watches for every setting and its default.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}GET
/A flight watch with every setting, defaults filled in. A near-me watch without a current location reads status: "waiting_location".
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}PATCH
/Changes a watch: fields sent replace the stored ones (nested objects whole). Owner, or an org admin for shared watches.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}POST
/Pauses a watch: the poller stops evaluating it and nothing is sent.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/pause' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}POST
/Resumes a paused watch.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/resume' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}POST
/Starts an ended watch again (it ended at its end time, or after its notification or flight limit) with its counters at zero. A watch whose end time has passed needs a new one (or none) first.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/restart' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watch: {
name: string
visibility: "org" | "private"
targets: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
exclude: {
kind: "any" | "type" | "hex" | "callsign" | "registration" | "preset" | "class" | "no_callsign"
value: string
}[]
areas: {
kind: "preset"
id: string
} | {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
}[]
limitToAreas: boolean
events: {
emergency?: boolean
takeoff?: boolean
landing?: boolean
signal_lost?: boolean
signal_resumed?: boolean
area_enter?: boolean
area_leave?: boolean
orbit?: boolean
road_follow?: boolean
road_switch?: boolean
road_repeat?: boolean
road_leave?: boolean
interchange?: boolean
threshold?: boolean
approach?: boolean
overhead?: boolean
}
settings: {
signal: {
lostAfterSeconds: number
lowAltitudeFt: number
}
orbit: {
turns: number
radiusKm: number
windowMinutes: number
maxAltitudeFt: null | number
loiterMinutes: null | number
ignoreAirportsKm: number
}
approach: {
lookaheadMinutes: number
minClosingKt: number
maxAltitudeFt: null | number
overheadKm: number
}
roads: {
corridorM: number
headingToleranceDeg: number
minSeconds: number
minShare: number
besideM: number
besideMinSeconds: number
besideMinMeters: number
repeatMinutes: number
endAfterSeconds: number
maxAltitudeFt: number
minSpeedKt: number
classes: ("primary" | "motorway" | "trunk")[]
}
thresholds: {
altitudeAboveFt?: number
altitudeBelowFt?: number
speedAboveKt?: number
speedBelowKt?: number
climbAboveFpm?: number
descentAboveFpm?: number
squawks?: string[]
}
}
notify: {
membershipNotices: boolean
liveActivity: boolean
smsEvents: null | ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
cooldownMinutes: number
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allow: ("emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead")[]
}
timeZone?: string
}
identity: {
mode: "any" | "pin_first"
pinnedHex: null | string
}
lifetime: {
startsAt: null | number
endsAt: null | number
maxNotifications: null | number
maxFlights: null | number
schedule: null | {
days: number[]
start: string
end: string
timeZone: string
}
forHours?: number
}
log: {
enabled: boolean
retentionDays: null | number
}
paused: boolean
watchId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
notificationsSent: number
flightsCompleted: number
endedAt?: number
endedReason?: "time" | "notifications" | "flights"
personal?: boolean
status: "active" | "waiting" | "paused" | "ended" | "off_schedule" | "waiting_location"
}
}POST
/Sends the caller a sample alert on the watch's channels that reach them and returns what each did: mobile (devices: phones with the Maps app, queued), web (sent, devices), email (sent), sms (sent, or skipped with why) and call (skipped). People only; maps:write, or the watch's owner.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/test' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
mobile?: {
devices: number
queued: boolean
}
web?: {
sent: number
devices: number
}
email?: {
sent?: boolean
skipped?: string
}
sms?: {
sent?: boolean
error?: string
skipped?: string
}
call?: {
skipped: string
}
}GET
/Flights the watch logged, newest first: airframe (hex, registration, callsign, type), start (takeoff or first_seen) and end (landing, lost, left, watch_ended, schedule), status (in_progress, completed, ended), distance, highest altitude, events and roads followed. hex filters to one airframe; pass the returned cursor for older ones.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
Query parameters
limitstringDefault
50.hexstringcursorstring
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/flights' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
flights: {
flightId: string
watchId: string
hex: string
registration?: string
callsign?: string
type?: string
desc?: string
status: "in_progress" | "completed" | "ended"
endReason?: string
startedAt: number
endedAt?: number
startedBy: "takeoff" | "first_seen"
start: {
lat: number
lon: number
alt: null | number
}
end?: {
lat: number
lon: number
alt: null | number
}
maxAlt: null | number
distanceNm: number
events: {
type: "emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead"
at: number
title: string
text: string
}[]
roads: {
label: string
from: number
to?: number
}[]
points?: ([number, number, number, null | number, null | number, null | number])[]
}[]
cursor: null | string
}GET
/One logged flight with its track (points: [seconds, lon, lat, altitude ft | null, ground speed kt, track°]).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).flightIdLogged flight id (
fgl_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/flights/{flightId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
flight: {
flightId: string
watchId: string
hex: string
registration?: string
callsign?: string
type?: string
desc?: string
status: "in_progress" | "completed" | "ended"
endReason?: string
startedAt: number
endedAt?: number
startedBy: "takeoff" | "first_seen"
start: {
lat: number
lon: number
alt: null | number
}
end?: {
lat: number
lon: number
alt: null | number
}
maxAlt: null | number
distanceNm: number
events: {
type: "emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead"
at: number
title: string
text: string
}[]
roads: {
label: string
from: number
to?: number
}[]
points?: ([number, number, number, null | number, null | number, null | number])[]
}
}GET
/A logged flight as a file: format=gpx (track and events as waypoints), kml (line and time-stamped track) or csv (one row per position, events alongside).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).flightIdLogged flight id (
fgl_…).
Query parameters
formatstringDefault
"gpx".
Errors
400format is gpx, kml or csv.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/flights/{flightId}/export' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200 with no body
DELETE
/Deletes a watch and its flight logs. Its events expire after 30 days.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/A watch's events, newest first (kept 30 days): type, aircraft, position, text, and what happened to the notification (sent with channels, quiet, no_recipients, failed). Pass the returned cursor for older ones.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).watchIdFlight watch id (
fwt_…).
Query parameters
limitstringDefault
50.cursorstring
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/watches/{watchId}/events' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
events: {
eventId: string
watchId: string
type: "emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead" | "recipients_added" | "recipients_removed" | "watch_started"
at: number
hex: string
title: string
text: string
aircraft: {
registration?: string
callsign?: string
type?: string
desc?: string
}
position?: {
lat: number
lon: number
alt: null | number
gs?: number
vs?: number
track?: number
}
data?: {
[key: string]: unknown
}
delivery?: {
status: "failed" | "sent" | "duplicate" | "quiet" | "cooldown" | "no_recipients"
channels?: ("email" | "sms" | "call" | "mobile" | "push" | "web")[]
recipients?: number
errors?: string[]
duplicates?: {
recipients: number
of: string[]
}
}
}[]
cursor: null | string
}GET
/Recent events across the watches the caller can see, newest first.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
limitstringDefault
50.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/events' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
events: {
eventId: string
watchId: string
type: "emergency" | "takeoff" | "landing" | "signal_lost" | "signal_resumed" | "area_enter" | "area_leave" | "orbit" | "road_follow" | "road_switch" | "road_repeat" | "road_leave" | "interchange" | "threshold" | "approach" | "overhead" | "recipients_added" | "recipients_removed" | "watch_started"
at: number
hex: string
title: string
text: string
aircraft: {
registration?: string
callsign?: string
type?: string
desc?: string
}
position?: {
lat: number
lon: number
alt: null | number
gs?: number
vs?: number
track?: number
}
data?: {
[key: string]: unknown
}
delivery?: {
status: "failed" | "sent" | "duplicate" | "quiet" | "cooldown" | "no_recipients"
channels?: ("email" | "sms" | "call" | "mobile" | "push" | "web")[]
recipients?: number
errors?: string[]
duplicates?: {
recipients: number
of: string[]
}
}
}[]
}GET
/Emergency incidents and warnings (Australia), from the incidents poller's picture: filtered to a view (bbox), hazards (hazards=bushfire,flood) and a minimum level (minLevel); sorted by distance from near=lon,lat (adds distanceKm), else most severe first; areas=0 leaves out warning areas (lists); limit. feeds carries each feed's credit line and licence. Answers 304 to a matching If-None-Match.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/incidents' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
updatedAt: null | number
feeds: {
sourceId: string
label: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA" | "AU"
attribution: string
licence: string
licenceUrl?: string
homepage?: string
count: number
ok: boolean
checkedAt?: number
changedAt?: number
error?: string
}[]
incidents: {
id: string
sourceId: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
kind: "warning" | "incident"
hazard: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
level: "none" | "advice" | "watch_and_act" | "emergency_warning"
status?: string
statusClass: "unknown" | "active" | "contained" | "controlled"
title: string
category?: string
location?: string
lga?: string
action?: string
description?: string
size?: string
agency?: string
resources?: number
updated: number
published?: number
url?: string
point: [number, number]
polygons?: [number, number][][][]
distanceKm?: number
}[]
total: number
etag: string
}Response 304 with no body
GET
/The emergency feeds in use: credit lines, licences, when each was last read and whether it's working.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/incidents/feeds' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
updatedAt: null | number
feeds: {
sourceId: string
label: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA" | "AU"
attribution: string
licence: string
licenceUrl?: string
homepage?: string
count: number
ok: boolean
checkedAt?: number
changedAt?: number
error?: string
}[]
}GET
/One incident (or its last version if it has ended) with its history of changes, newest first.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).incidentIdIncident id as listed (
<feed>:<the agency's id>, e.g.vic:ESTA:261009192), URL-encoded.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/incidents/{incidentId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
incident: null | {
id: string
sourceId: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
kind: "warning" | "incident"
hazard: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
level: "none" | "advice" | "watch_and_act" | "emergency_warning"
status?: string
statusClass: "unknown" | "active" | "contained" | "controlled"
title: string
category?: string
location?: string
lga?: string
action?: string
description?: string
size?: string
agency?: string
resources?: number
updated: number
published?: number
url?: string
point: [number, number]
polygons?: [number, number][][][]
}
ended: boolean
history: {
at: number
change: string
incident: {
url?: string
status?: string
kind: "warning" | "incident"
level: "none" | "advice" | "watch_and_act" | "emergency_warning"
title: string
description?: string
location?: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
id: string
size?: string
category?: string
action?: string
sourceId: string
published?: number
resources?: number
updated: number
hazard: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
statusClass: "unknown" | "active" | "contained" | "controlled"
lga?: string
agency?: string
point: [number, number]
}
}[]
feed?: {
sourceId: string
label: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA" | "AU"
attribution: string
licence: string
licenceUrl?: string
homepage?: string
count: number
ok: boolean
checkedAt?: number
changedAt?: number
error?: string
}
}GET
/Hazards, levels, zone events, states and a new zone's defaults for the caller.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/config' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
hazards: {
id: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
label: string
icon: string
glyph: "car" | "tree" | "info" | "cyclone" | "smoke" | "flame" | "grass" | "burn" | "house" | "drop" | "bolt" | "sun" | "wave" | "quake" | "slope" | "hazard" | "buoy" | "cross" | "plug" | "paw"
group: string
}[]
hazardGroups: {
id: string
label: string
}[]
levels: {
id: "none" | "advice" | "watch_and_act" | "emergency_warning"
label: string
callToAction: null | string
token: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground" | "primary" | "destructive" | "muted-foreground" | "background" | "incident" | "map-horizon" | "map-sky" | "map-space" | "incident-foreground" | "warning-advice" | "warning-advice-foreground" | "warning-watch" | "warning-watch-foreground" | "warning-emergency" | "warning-emergency-foreground"
foreground: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground" | "primary" | "destructive" | "muted-foreground" | "background" | "incident" | "map-horizon" | "map-sky" | "map-space" | "incident-foreground" | "warning-advice" | "warning-advice-foreground" | "warning-watch" | "warning-watch-foreground" | "warning-emergency" | "warning-emergency-foreground"
}[]
statuses: {
id: "unknown" | "active" | "contained" | "controlled"
label: string
}[]
events: {
type: "closed" | "new" | "updated" | "escalated" | "downgraded"
label: string
}[]
states: {
id: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
label: string
}[]
defaults: {
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
events: {
closed: boolean
new: boolean
updated: boolean
escalated: boolean
downgraded: boolean
}
}
}GET
/Watch zones: areas where emergency incidents and warnings alert (those the caller can see).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
zones: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}[]
}POST
/Creates a watch zone: areas (circle, polygon, location, near_me or state; up to 10), hazards (empty: all), minLevel, events and notify (channels, people, groups, smsEvents, smsMinLevel, quiet hours with allowLevels). Channels left out get the caller's defaults.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
zone: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}
}GET
/One watch zone, with its status (active, paused or waiting_location for a near-me zone without a current location).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
zone: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}
}PATCH
/Changes a watch zone (its owner, or an org admin for org zones): fields sent replace the stored ones.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
zone: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}
}POST
/Pauses a watch zone: nothing is checked or sent until it's resumed.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}/pause' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
zone: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}
}POST
/Resumes a paused watch zone.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}/resume' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
zone: {
name: string
visibility: "org" | "private"
areas: {
kind: "circle"
center: [number, number]
radiusKm: number
label?: string
} | {
kind: "polygon"
ring: [number, number][]
label?: string
} | {
kind: "location"
locationId: string
radiusKm: number
} | {
kind: "near_me"
radiusKm: number
} | {
kind: "state"
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
}[]
hazards: ("other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal")[]
minLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
events: {
closed?: boolean
new?: boolean
updated?: boolean
escalated?: boolean
downgraded?: boolean
}
notify: {
smsEvents: null | ("closed" | "new" | "updated" | "escalated" | "downgraded")[]
smsMinLevel: "none" | "advice" | "watch_and_act" | "emergency_warning"
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
includeOwner: boolean
groupIds: string[]
userIds: string[]
smsFormat: "full" | "short"
smsPrefix: boolean
quietHours?: null | {
start: string
end: string
timeZone: string
allowLevels: ("none" | "advice" | "watch_and_act" | "emergency_warning")[]
}
timeZone?: string
}
paused: boolean
zoneId: string
orgId: string
ownerId: string
createdAt: number
updatedAt: number
lastEventAt?: number
alertsSent: number
personal?: boolean
status: "active" | "paused" | "waiting_location"
}
}POST
/Sends the caller a sample alert on the zone's channels that reach them; per-channel results.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}/test' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
mobile?: {
devices: number
queued: boolean
}
web?: {
sent: number
devices: number
}
email?: {
sent?: boolean
skipped?: string
}
sms?: {
sent?: boolean
error?: string
skipped?: string
}
call?: {
skipped: string
}
}GET
/A watch zone's alerts, newest first (limit, cursor): the change, the incident as it was, the distance and what was sent. Kept 30 days (7 for near-me zones).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
Query parameters
limitstringDefault
50.cursorstring
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}/events' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
events: {
eventId: string
zoneId: string
type: "closed" | "new" | "updated" | "escalated" | "downgraded"
at: number
incidentId: string
title: string
text: string
from?: "none" | "advice" | "watch_and_act" | "emergency_warning"
incident: {
url?: string
status?: string
kind: "warning" | "incident"
level: "none" | "advice" | "watch_and_act" | "emergency_warning"
title: string
description?: string
location?: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
id: string
size?: string
category?: string
action?: string
sourceId: string
published?: number
resources?: number
updated: number
hazard: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
statusClass: "unknown" | "active" | "contained" | "controlled"
lga?: string
agency?: string
point: [number, number]
}
distanceKm?: number
delivery?: {
status: "failed" | "sent" | "duplicate" | "quiet" | "no_recipients"
channels?: string[]
recipients?: number
errors?: string[]
duplicates?: {
recipients: number
}
}
}[]
cursor: null | string
}DELETE
/Deletes a watch zone. Its alerts expire on their own.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).zoneIdWatch zone id (
izn_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zones/{zoneId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/Recent zone alerts across the zones the caller can see.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
Query parameters
limitstringDefault
50.
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/zone-events' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
events: {
eventId: string
zoneId: string
type: "closed" | "new" | "updated" | "escalated" | "downgraded"
at: number
incidentId: string
title: string
text: string
from?: "none" | "advice" | "watch_and_act" | "emergency_warning"
incident: {
url?: string
status?: string
kind: "warning" | "incident"
level: "none" | "advice" | "watch_and_act" | "emergency_warning"
title: string
description?: string
location?: string
state: "ACT" | "NSW" | "NT" | "QLD" | "SA" | "TAS" | "VIC" | "WA"
id: string
size?: string
category?: string
action?: string
sourceId: string
published?: number
resources?: number
updated: number
hazard: "other" | "bushfire" | "grass_fire" | "burn_off" | "structure_fire" | "vehicle_fire" | "fire" | "flood" | "storm" | "cyclone" | "tree_down" | "heat" | "tsunami" | "earthquake" | "landslide" | "hazmat" | "smoke" | "rescue" | "medical" | "accident" | "power" | "animal"
statusClass: "unknown" | "active" | "contained" | "controlled"
lga?: string
agency?: string
point: [number, number]
}
distanceKm?: number
delivery?: {
status: "failed" | "sent" | "duplicate" | "quiet" | "no_recipients"
channels?: string[]
recipients?: number
errors?: string[]
duplicates?: {
recipients: number
}
}
}[]
}GET
/The org's alert locations: locationId, name, lat, lon, siteRadiusM (within it counts as on site), address, note, icon, color, ownerId.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
locations: {
locationId: string
orgId: string
name: string
lat: number
lon: number
siteRadiusM: number
address?: string
note?: string
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
ownerId: string
createdAt: number
updatedAt: number
}[]
}POST
/Creates an alert location: name, lat, lon, siteRadiusM (50–5,000 m, default 300), optional address, note, icon, color. Up to 50 per organization.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
location: {
locationId: string
orgId: string
name: string
lat: number
lon: number
siteRadiusM: number
address?: string
note?: string
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
ownerId: string
createdAt: number
updatedAt: number
}
}GET
/One alert location.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).locationIdLocation id: a platform location, or under Maps an org's alert location (
mlc_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations/{locationId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
location: {
locationId: string
orgId: string
name: string
lat: number
lon: number
siteRadiusM: number
address?: string
note?: string
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
ownerId: string
createdAt: number
updatedAt: number
}
}PATCH
/Changes an alert location; fields sent replace the stored ones. Moving it moves every watch that uses it. Its owner or an org admin.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).locationIdLocation id: a platform location, or under Maps an org's alert location (
mlc_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations/{locationId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
location: {
locationId: string
orgId: string
name: string
lat: number
lon: number
siteRadiusM: number
address?: string
note?: string
icon: "map-pin" | "star" | "heart" | "home" | "briefcase" | "utensils" | "coffee" | "plane" | "helicopter" | "flag" | "camera" | "car" | "tent" | "hospital" | "shield"
color: "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "foreground"
ownerId: string
createdAt: number
updatedAt: number
}
}DELETE
/Deletes an alert location. 409, naming them, while watches use it. Its owner or an org admin.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).locationIdLocation id: a platform location, or under Maps an org's alert location (
mlc_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations/{locationId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/Watches that alert near a location (watchId, name), those the caller can see.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).locationIdLocation id: a platform location, or under Maps an org's alert location (
mlc_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/locations/{locationId}/watches' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
watches: {
watchId: string
name: string
}[]
}GET
/Notification groups with counts of active, pending and unsubscribed recipients.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
groups: {
counts: {
active: number
pending: number
unsubscribed: number
}
canEdit: boolean
groupId: string
orgId: string
name: string
ownerId: string
createdAt: number
updatedAt: number
}[]
}POST
/Creates a notification group (name).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
group: {
groupId: string
orgId: string
name: string
ownerId: string
createdAt: number
updatedAt: number
}
}GET
/A group and, for its owner and org admins, its recipients.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
group: {
members: {
memberId: string
groupId: string
kind: "user" | "contact"
userId?: string
name?: string
email?: string
phone?: string
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
status: "active" | "pending" | "unsubscribed"
createdAt: number
confirmedAt?: number
unsubscribedAt?: number
}[]
canEdit: boolean
groupId: string
orgId: string
name: string
ownerId: string
createdAt: number
updatedAt: number
}
}PATCH
/Renames a group.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
group: {
groupId: string
orgId: string
name: string
ownerId: string
createdAt: number
updatedAt: number
}
}DELETE
/Deletes a group and its recipients. Watches that used it stop sending to them.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}POST
/Adds a recipient: an organization member ({ kind: "user", userId }, active at once) or anyone ({ kind: "contact", name?, email?, phone? } with phone in E.164), who is asked to confirm first and stays pending until they do. channels limits what they get.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}/members' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
member: {
memberId: string
groupId: string
kind: "user" | "contact"
userId?: string
name?: string
email?: string
phone?: string
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
status: "active" | "pending" | "unsubscribed"
createdAt: number
confirmedAt?: number
unsubscribedAt?: number
}
invited: boolean
}PATCH
/Changes a recipient's name or channels.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).memberIdRecipient id (
nmb_…).
Errors
400Send JSON.
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}/members/{memberId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
member: {
memberId: string
groupId: string
kind: "user" | "contact"
userId?: string
name?: string
email?: string
phone?: string
channels: ("email" | "sms" | "call" | "mobile" | "web")[]
status: "active" | "pending" | "unsubscribed"
createdAt: number
confirmedAt?: number
unsubscribedAt?: number
}
}POST
/Asks a pending recipient to confirm again (at most three times, an hour apart).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).memberIdRecipient id (
nmb_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}/members/{memberId}/resend' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
invited: boolean
}DELETE
/Removes a recipient.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).groupIdNotification group id (
ngr_…).memberIdRecipient id (
nmb_…).
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/groups/{groupId}/members/{memberId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/Where the caller's alerts can go: the web push public key (VAPID), browsers with web push (subscriptions) and phones that get Maps alerts (phones: deviceId, appId maps, or home on phones without the Maps app, name, model, platform, appVersion, updatedAt).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/push' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
publicKey: string
subscriptions: {
subId: string
label?: string
host: string
createdAt: number
lastUsedAt?: number
}[]
phones: {
deviceId: string
appId: "maps" | "home"
name?: string
model?: string
platform: string
appVersion?: string
updatedAt?: number
}[]
}POST
/Sends the caller a sample alert on their phones (Maps app) and browsers: mobile (devices, queued) and web (sent, devices).
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/push/test' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
mobile?: {
devices: number
queued: boolean
}
web?: {
sent: number
devices: number
}
email?: {
sent?: boolean
skipped?: string
}
sms?: {
sent?: boolean
error?: string
skipped?: string
}
call?: {
skipped: string
}
}POST
/Subscribes a device to web push: the browser's PushSubscription (endpoint, keys.p256dh, keys.auth) and an optional label. People only; up to 20 devices.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scopes
- maps:read, maps:write
Path parameters
orgIdOrganization id (
org_…).
Errors
400Send JSON.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/push/subscriptions' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
subId: string
}DELETE
/Removes one of the caller's devices.
- Auth
- A person's token or an API key, as Authorization: Bearer.
- Scope
- maps:read
Path parameters
orgIdOrganization id (
org_…).subIdPush subscription id, as listed by
GET /v1/orgs/:orgId/maps/push.
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/maps/push/subscriptions/{subId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
}GET
/Your location for near-me alerts: sharing, the phones sharing (devices: deviceId, platform, name, mode foreground or background, retentionHours, enabledAt, lastReportAt), the current fix (current: lat, lon to 3 decimals, accuracyM, at, deviceName, validUntil, or null) and the near-me watches using it (usedBy). From the Maps or mobile apps only.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Your location is yours: open it in the Maps app.
curl 'https://api.cactive.com.au/v1/me/maps/location' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
sharing: boolean
devices: {
lastReportAt?: number
mode: "foreground" | "background"
findMy: boolean
retentionHours: number
enabledAt: number
name?: string
deviceId: string
platform: string
}[]
current: null | {
deviceId: string
mode: string
validUntil: number
deviceName?: string
lat: number
lon: number
accuracyM: number
at: number
}
usedBy: {
orgId: string
watchId: string
name: string
}[]
}PUT
/Turns sharing on for this phone or changes it: platform, name, mode (foreground: counts 30 minutes after each report; background: retentionHours 1, 6 or 24 after the last report). A background phone gets its report key (key, si_loc_…) once. Mobile app tokens only, tied to their sign-in.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Errors
400Send JSON.403Your location is yours: open it in the Maps app.403Phones share their location from the Maps app.
curl -X PUT 'https://api.cactive.com.au/v1/me/maps/location/devices/{deviceId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
key?: string
device: {
lastReportAt?: number
mode: "foreground" | "background"
findMy: boolean
retentionHours: number
enabledAt: number
name?: string
deviceId: string
platform: string
}
}POST
/Reports this phone's location: lat, lon, accuracyM, at (ms; at most 10 minutes old), source (foreground, significant, region, open). Stored to 3 decimals, accuracy at least 50 m, one current fix per phone; 204 when dropped (one report per 20 s). Mobile app tokens only.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Errors
400Send JSON.403Your location is yours: open it in the Maps app.403Phones share their location from the Maps app.
curl -X POST 'https://api.cactive.com.au/v1/me/maps/location/devices/{deviceId}/report' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: true
validUntil?: number
}Response 204 with no body
DELETE
/Stops sharing on one phone: its fix and key are deleted.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Errors
403Your location is yours: open it in the Maps app.
curl -X DELETE 'https://api.cactive.com.au/v1/me/maps/location/devices/{deviceId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
ok: boolean
}DELETE
/Deletes your location everywhere: every phone's fix, the phones and their keys. Near-me watches wait until a phone shares again.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Your location is yours: open it in the Maps app.
curl -X DELETE 'https://api.cactive.com.au/v1/me/maps/location' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
devices: number
ok: true
}GET
/Your own log of turning sharing on, background on, stopping, deleting and phones removed at sign-out (action, at, deviceName), kept 90 days. Never coordinates.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Query parameters
limitstringDefault
50.
Errors
403Your location is yours: open it in the Maps app.
curl 'https://api.cactive.com.au/v1/me/maps/location/activity' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
activity: {
deviceName?: string
action: string
at: number
}[]
}GET
/{ cars }: the cars you see, where you may see them (Vehicles' sharing rules), with their state, battery and picture. Empty where Vehicles isn't available.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/me/maps/cars' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
cars: {
vehicleId: string
name: string
model?: string
owned: boolean
ownerSpace: string
state?: string
soc?: number
lastSeen?: number
position?: {
lat: number
lon: number
accuracyM?: number
approximate?: true
headingDeg?: number
place?: string
at?: number
}
precision: "hidden" | "exact" | "approximate"
capabilities: string[]
offline: boolean
watches: {
leftBehind: boolean
found: boolean
}
colour?: string
art?: string
picture?: {
views: {
"3qtr"?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
side?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
}
approximate?: true
source: string
}
}[]
}POST
/Where the cars you see have been (docs/maps/timeline.md → Trails): each car's drive so far, or its last drive when it parked recently, as Vehicles shows it to you; null for a car with nothing to show (whatever the reason). Each ask says what you hold, so the answer has only what's new.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
carsobject[]required1–10 items.
cars[].vehicleIdstringrequiredMatches
^veh_[0-9a-z]{8,40}$.cars[].tripIdstringMatches
^drv_[0-9a-z]{8,40}$.cars[].sinceinteger≥ 0.
cars[].stretchinteger0–1000.
cars[].roadbooleancars[].doneboolean
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/me/maps/cars/trails' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"cars": [
{
"vehicleId": "<vehicleId>"
}
]
}'Send it from this page with your session or a key.
Response 200
{
trails: {
[key: string]: null
}
}
| {
trails: {
[key: string]: null | {
tripId: string
open: boolean
startedAt: number
endedAt?: number
points: [number, number, number][]
through?: number
replace?: true
stretches?: {
from: number
lines: (null | {
road: boolean
points: object
from: number
to: number
t?: object
}[])[]
}
road?: null | {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
roadPending?: true
} | {
keep: true
}
}
}GET
/One page of what happened between from and to (ISO dates or epoch milliseconds, at most 31 days): { range, items, sources, next?, keeps }. sources (vehicles, flights, people; all by default) picks what is read. next.to asks for the earlier part.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
400Give from and to (ISO dates or epoch milliseconds).403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl 'https://api.cactive.com.au/v1/me/maps/timeline' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
range: {
from: number
to: number
}
items: {
id: string
source: "events" | "photos" | "vehicles" | "people" | "flights"
kind: "drive" | "photos" | "event" | "charge" | "trail" | "flight" | "parked" | "flight_event" | "visit"
at: number
end?: number
title: string
detail?: string
line?: [number, number][]
times?: number[]
road?: {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
roadPending?: true
point?: [number, number]
timed?: boolean
subject?: string
ref: {
vehicleId?: string
tripId?: string
chargeId?: string
idleId?: string
watchId?: string
flightId?: string
deviceId?: string
photoId?: string
orgSlug?: string
mailboxId?: string
calendarId?: string
eventId?: string
date?: string
}
count?: number
placesHidden?: true
distanceKm?: number
}[]
sources: {
events?: "ok" | "none" | "off"
photos?: "ok" | "none" | "off"
vehicles?: "ok" | "none" | "off"
people?: "ok" | "none" | "off"
flights?: "ok" | "none" | "off"
}
next?: {
to: number
}
keeps: {
trailHours: number
}
}GET
/{ layers: { photos, events, traffic, tasks } }: which of the map's other layers you may turn on here (docs/maps/layers.md): scopes and the org's app switches.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403This is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/maps/layers' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
layers: {
events: boolean
photos: boolean
tasks: boolean
traffic: boolean
}
}GET
/A photo's card on the map: { photo: { photoId, kind, takenAt, thumbUrl? } }, for one of your own located photos.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
photoIdPhoto id: the photo's file in Drive (
fil_…).
Errors
403This is yours: open it in the Maps app.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:read404Photo not found
curl 'https://api.cactive.com.au/v1/me/maps/layers/photos/{photoId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
photo: {
thumbUrl?: string
photoId: string
kind: "raw" | "video" | "live" | "photo"
takenAt: number
}
}GET
/A layer's things (LayerAnswer): photos (your own, in bbox), events (your events from yesterday to a month ahead, at their places), traffic (your organisation's Cloud traffic by country, the last 7 days) or tasks (your organisation's Tasks issues with a place in bbox, as you can open them in Tasks; spaces (keys) and status (todo, inprogress, done) filter them, open work by default). bbox is west,south,east,north; the answer's box says what it covers (everywhere for events and traffic). state: "off" where it isn't yours to see here.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
layerOne of the map's other layers:
photos(your own),events(your calendar events at their places) ortraffic(your organisation's Cloud traffic by country).
Query parameters
bboxstringspacesstringstatusstring
Errors
400Give bbox as west,south,east,north in degrees.403This is yours: open it in the Maps app.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:read404No such layer.404Serverless App Service not found
curl 'https://api.cactive.com.au/v1/me/maps/layers/{layer}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
layer: "events" | "photos" | "tasks" | "traffic"
box: [number, number, number, number]
items: {
id: string
layer: "events" | "photos" | "tasks" | "traffic"
lat: number
lon: number
title: string
at?: number
end?: number
allDay?: boolean
detail?: string
status?: string
space?: string
category?: "done" | "todo" | "inprogress"
weight?: number
kind?: "video" | "photo"
ref: {
photoId?: string
orgId?: string
orgSlug?: string
mailboxId?: string
calendarId?: string
eventId?: string
calendar?: string
date?: string
country?: string
issueKey?: string
}
}[]
state: "ok" | "off"
truncated?: true
unplaced?: number
total?: number
filter?: string
spaces?: {
key: string
name: string
}[]
}GET
/A drive on the timeline with its track, for playback: as Vehicles' drive detail answers it, for a drive you see.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
400Not a drive.403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.404Drive not found
curl 'https://api.cactive.com.au/v1/me/maps/timeline/drives/{vehicleId}/{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
}[]
}
}POST
/Drives' lines on the roads they took ({ drives: [{ vehicleId, tripId }] }, up to 50): { roads: { [tripId]: stretches | "pending" | null } }. Display only.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
drivesobject[]required1–50 items.
drives[].vehicleIdstringrequiredMatches
^veh_[0-9a-z]{8,40}$.drives[].tripIdstringrequiredMatches
^drv_[0-9a-z]{8,40}$.
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read404Vehicles isn't available here.
curl -X POST 'https://api.cactive.com.au/v1/me/maps/timeline/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"drives": [
{
"vehicleId": "<vehicleId>",
"tripId": "<tripId>"
}
]
}'Send it from this page with your session or a key.
Response 200
{
roads: {}
}
| {
roads: {
[key: string]: null | "pending" | {
road: boolean
points: [number, number][]
from: number
to: number
t?: [number, number]
}[]
}
}POST
/Directions (docs/maps/directions.md): { from, to, mode } (drive with live traffic, walk, cycle) answers { routes } (the best and up to two alternatives, with steps; a drive's traffic) or { error: "no_route" | "too_far" | "unavailable" }. POST, so the points stay out of URLs and logs; they go to Mapbox for this request only. Counted per person per hour (maps.directions.routesPerHour): past it, 429 with Retry-After.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
fromobjectrequiredfrom.latnumberrequired-90–90.
from.lonnumberrequired-180–180.
toobjectrequiredto.latnumberrequired-90–90.
to.lonnumberrequired-180–180.
mode"drive" | "walk" | "cycle"required
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read
curl -X POST 'https://api.cactive.com.au/v1/me/maps/directions' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"from": {
"lat": 1,
"lon": 1
},
"to": {
"lat": 1,
"lon": 1
},
"mode": "drive"
}'Send it from this page with your session or a key.
Response 200
{
routes?: {
distanceM: number
durationS: number
typicalS?: number
name: string
line: [number, number][]
congestion: {
from: number
to: number
level: "heavy" | "moderate" | "severe"
}[]
steps: {
instruction: string
distanceM: number
durationS: number
maneuver: {
type: string
modifier?: string
}
at: [number, number]
road?: string
}[]
}[]
error?: "unavailable" | "no_route" | "too_far"
}GET
/{ on, available }: whether you draw drives on the roads they took (on unless you turned it off), and whether there are drives here.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403This is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/maps/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
on: boolean
available: boolean
}PUT
/Draws drives on the roads they took, or as driven ({ on }): your choice, shared with Vehicles' Display.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
onbooleanrequired
Also checked: Unknown fields are rejected.
Errors
403This is yours: open it in the Maps app.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:read409There are no drives to draw here.
curl -X PUT 'https://api.cactive.com.au/v1/me/maps/roads' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"on": true
}'Send it from this page with your session or a key.
Response 200
{
on: boolean
}GET
/{ mine, shared }: the person's own trips that still run, with who sees them, and the trips shared with them (and offers).
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/eta' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
mine: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}[]
shared: {
tripId: string
from: {
userId: string
name: null | string
email: null | string
}
status: "active" | "stopped" | "arrived"
offer: null | {
key: string
}
mode: null | "drive" | "walk" | "cycle"
to: null | {
lat: number
lon: number
name?: string
personId?: string
}
heading: null | string
startedAt: null | number
endsAt: number
endedAt: null | number
etaAt: null | number
remainingM: null | number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
}[]
}POST
/Starts sharing a trip: { to: { lat, lon, name? }, mode, durationS, etaAt, remainingM, position?, recipients: [userId] }. 201 { trip, shared }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
toobjectrequiredto.latnumberrequired-90–90.
to.lonnumberrequired-180–180.
to.namestringUp to 120 characters. Trimmed.
to.personIdstringMatches
^usr_[A-Za-z0-9]{6,60}$.mode"drive" | "walk" | "cycle"requireddurationSintegerrequired0–604800.
etaAtintegerrequired> 0.
remainingMnumberrequired0–40000000.
positionobjectposition.latnumberrequired-90–90.
position.lonnumberrequired-180–180.
position.accuracyMnumber0–100000.
recipientsstring[]required1–50 items. Each matches
^usr_[A-Za-z0-9]{6,60}$.
Also checked: Unknown fields are rejected.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/eta' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"to": {
"lat": 1,
"lon": 1
},
"mode": "drive",
"durationS": 1,
"etaAt": 1,
"remainingM": 1,
"recipients": [
"example"
]
}'Send it from this page with your session or a key.
Response 201
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
shared: {
userId: string
status: "active" | "pending" | "refused"
error?: string
}[]
}GET
/A trip: { mine } for its sharer, { shared } for someone it's shared with (or an offer to accept), else 404.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
mine?: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
shared?: {
tripId: string
from: {
userId: string
name: null | string
email: null | string
}
status: "active" | "stopped" | "arrived"
offer: null | {
key: string
}
mode: null | "drive" | "walk" | "cycle"
to: null | {
lat: number
lon: number
name?: string
personId?: string
}
heading: null | string
startedAt: null | number
endsAt: number
endedAt: null | number
etaAt: null | number
remainingM: null | number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
}
}POST
/The sharer's progress: { lat, lon, accuracyM?, etaAt, remainingM }. Near the destination it arrives. { trip }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Request body
latnumberrequired-90–90.
lonnumberrequired-180–180.
accuracyMnumber0–100000.
etaAtintegerrequired> 0.
remainingMnumberrequired0–40000000.
Also checked: Unknown fields are rejected.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/progress' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"lat": 1,
"lon": 1,
"etaAt": 1,
"remainingM": 1
}'Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}POST
/Shares a running trip with more people: { recipients: [userId] }. { trip, shared }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Request body
recipientsstring[]required1–50 items. Each matches
^usr_[A-Za-z0-9]{6,60}$.
Also checked: Unknown fields are rejected.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/recipients' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"recipients": [
"example"
]
}'Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
shared: {
userId: string
status: "active" | "pending" | "refused"
error?: string
}[]
}DELETE
/Stops sharing a trip with one person, at once.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.userIdA member's user id (
usr_…).
Errors
400Not a person's id.403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/recipients/{userId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}POST
/Shares a running trip for longer: { minutes } (5 to 1,440), up to maps.eta.hoursMax after its start. { trip }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Request body
minutesintegerrequired5–1440.
Also checked: Unknown fields are rejected.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/extend' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"minutes": 1
}'Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}POST
/A link to the trip for someone without an account: 201 { url, link, trip }. The address is answered this once (the token is in its fragment) for the person to send themselves; it ends with the trip, or when they end it.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/links' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 201
{
url: string
link: {
linkId: string
createdAt: number
expiresAt: null | number
}
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}DELETE
/Ends one of the trip's links, at once. { trip }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.linkIdLink 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
403Find My is yours: open it in the Maps app.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:write404That link isn't there.
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/links/{linkId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}DELETE
/Stops following someone's trip (the share given back).
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}/following' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
left: boolean
}DELETE
/Stops sharing a trip with everyone, at once.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
tripIdA drive's id (
drv_…), as the drives list gives it.
Errors
403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/eta/{tripId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
trip: {
tripId: string
mode: "drive" | "walk" | "cycle"
to: {
lat: number
lon: number
name?: string
personId?: string
}
status: "active" | "stopped" | "arrived"
startedAt: number
endsAt: number
extendableTo: number
endedAt: null | number
etaAt: number
remainingM: number
position: null | {
lat: number
lon: number
accuracyM: number
at: number
}
recipients: {
userId: string
name: null | string
email: null | string
status: "active" | "pending"
}[]
links: {
linkId: string
createdAt: number
expiresAt: null | number
}[]
}
}GET
/{ me, people }: the person, and everyone they share with, who shares with them, or who asked; where each is, as they may see it.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/people' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
me: {
sharing: "off" | "hidden" | "on"
hiddenUntil: null | number
placeNames: boolean
device: null | {
deviceId: string
name: null | string
platform: string
mode: string
lastReportAt: null | number
}
location: null | {
lat: number
lon: number
accuracyM: number
at: number
approximate?: true
battery?: number
charging?: boolean
}
}
people: {
userId: string
name: null | string
email: null | string
theirs: null | {
location: null | {
lat: number
lon: number
accuracyM: number
at: number
approximate?: true
battery?: number
charging?: boolean
}
precision: "hidden" | "exact" | "approximate"
expiresAt: null | number
since: string
}
mine: null | {
status: "active" | "pending"
precision: "exact" | "approximate"
expiresAt: null | number
pausedUntil: null | number
rev: number
since: string
}
offer: null | {
key: string
acceptBy: null | number
}
request: null | "incoming" | "outgoing"
alerts: {
alertId: string
subjectId: string
name: string
lat: number
lon: number
radiusM: number
on: "arrive" | "leave" | "both"
repeat: boolean
createdAt: string
}[]
}[]
}GET
/Home's People widget: { people }, everyone who shares with the person, most recently seen first (10 at most): when, and where in words ("At Mum's", "Near your Work", or their own place names when they show them on an exact share) or how far from lat/lon (where the phone is, optional). No coordinates; each look is a use, as People's.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Query parameters
latstringlonstring
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/widget/people' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
people: {
userId: string
name: null | string
email: null | string
at: null | number
where: null | string
distanceM: null | number
approximate: boolean
}[]
}GET
/Home's Devices widget: { phones, cars }, the person's own phones and the cars they see, with battery and when last seen. No positions.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read403Find My is for people, not keys.
curl 'https://api.cactive.com.au/v1/me/findmy/widget/devices' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
phones: {
deviceId: string
name: null | string
battery?: number
charging?: boolean
lastSeenAt: null | number
offline: boolean
}[]
cars: {
vehicleId: string
name: string
soc?: number
state?: string
lastSeen: null | number
offline: boolean
}[]
}PUT
/"Show my place names to people I share with" ({ on }): their own places' names, to exact shares only. Answers me.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
400Send { on: true } or { on: false }.403Find My is yours: open it in the Maps app.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
curl -X PUT 'https://api.cactive.com.au/v1/me/findmy/place-names' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
me: {
sharing: "off" | "hidden" | "on"
hiddenUntil: null | number
placeNames: boolean
device: null | {
deviceId: string
name: null | string
platform: string
mode: string
lastReportAt: null | number
}
location: null | {
lat: number
lon: number
accuracyM: number
at: number
approximate?: true
battery?: number
charging?: boolean
}
}
}GET
/{ people }: Mirage friends, circles and Find My people to share with.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/suggestions' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
people: {
userId: string
name: null | string
email: null | string
}[]
}PUT
/Hides it from everyone: { until } (a time or forever) or { off: true } (Share My Location off). DELETE shows it again.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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
curl -X PUT 'https://api.cactive.com.au/v1/me/findmy/hide' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
me: {
sharing: "off" | "hidden" | "on"
hiddenUntil: null | number
placeNames: boolean
device: null | {
deviceId: string
name: null | string
platform: string
mode: string
lastReportAt: null | number
}
location: null | {
lat: number
lon: number
accuracyM: number
at: number
approximate?: true
battery?: number
charging?: boolean
}
}
}DELETE
/Shows your location to everyone you share with again: ends a hide or turns Share My Location back on.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/hide' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
me: {
sharing: "off" | "hidden" | "on"
hiddenUntil: null | number
placeNames: boolean
device: null | {
deviceId: string
name: null | string
platform: string
mode: string
lastReportAt: null | number
}
location: null | {
lat: number
lon: number
accuracyM: number
at: number
approximate?: true
battery?: number
charging?: boolean
}
}
}DELETE
/Stops seeing someone's location (gives their share back).
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
userIdA member's user id (
usr_…).
Errors
400Not a person's id.403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/following/{userId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
stopped: boolean
}POST
/Asks someone to share their location: { email | userId }. Always { sent: true }, account or not. Spends one of the day's shares.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
emailstring3–254 characters. Trimmed.
userIdstringUp to 80 characters.
Also checked: Unknown fields are rejected. Name the person by email address or user id.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/requests' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"email": "person@example.com",
"userId": "<userId>"
}'Send it from this page with your session or a key.
Response 202
{
sent: boolean
}POST
/Shares your location with someone who asked (precision optional); they see you at once, with no offer to accept. The request goes.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
userIdA member's user id (
usr_…).
Request body
precision"approximate" | "exact"
Also checked: Unknown fields are rejected.
Errors
400Not a person's id.403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/requests/{userId}/accept' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"precision": "approximate"
}'Send it from this page with your session or a key.
Response 200
{
shared: boolean
result?: undefined
} | {
shared: boolean
result: {
kind: "grant"
grant: {
resource: string
principal: string
kind: "user" | "key" | "org" | "link" | "group" | "circle"
name: null | string
email: null | string
deleted: boolean
source: string
status: "active" | "pending"
capabilities: string[]
preset: null | string
notBefore: null | number
expiresAt: null | number
schedule: null | {
tz: string
windows: {
days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
from: string
to: string
dates?: string[]
}[]
}
params: null | {
[key: string]: boolean | string | number
}
assistants: boolean
approval: string[]
includeGuests: boolean
external: boolean
blocked: null | string
acceptBy: null | number
pausedUntil: null | number
grantedBy: {
id: string
name: null | string
}
createdAt: string
updatedAt: string
rev: number
}
} | {
kind: "invitation"
invitation: {
invitationId: string
principal: string
email: string
capabilities: string[]
preset: null | string
notBefore: null | number
expiresAt: null | number
schedule: null | {
tz: string
windows: {
days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
from: string
to: string
dates?: string[]
}[]
}
params: null | {
[key: string]: boolean | string | number
}
assistants: boolean
approval: string[]
offerEnds: number
invitedBy: {
id: string
name: null | string
}
createdAt: string
}
}
}POST
/Declines someone's request to see your location. They aren't told.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
userIdA member's user id (
usr_…).
Errors
400Not a person's id.403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/requests/{userId}/decline' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
shared: boolean
result?: undefined
} | {
shared: boolean
result: {
kind: "grant"
grant: {
resource: string
principal: string
kind: "user" | "key" | "org" | "link" | "group" | "circle"
name: null | string
email: null | string
deleted: boolean
source: string
status: "active" | "pending"
capabilities: string[]
preset: null | string
notBefore: null | number
expiresAt: null | number
schedule: null | {
tz: string
windows: {
days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
from: string
to: string
dates?: string[]
}[]
}
params: null | {
[key: string]: boolean | string | number
}
assistants: boolean
approval: string[]
includeGuests: boolean
external: boolean
blocked: null | string
acceptBy: null | number
pausedUntil: null | number
grantedBy: {
id: string
name: null | string
}
createdAt: string
updatedAt: string
rev: number
}
} | {
kind: "invitation"
invitation: {
invitationId: string
principal: string
email: string
capabilities: string[]
preset: null | string
notBefore: null | number
expiresAt: null | number
schedule: null | {
tz: string
windows: {
days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
from: string
to: string
dates?: string[]
}[]
}
params: null | {
[key: string]: boolean | string | number
}
assistants: boolean
approval: string[]
offerEnds: number
invitedBy: {
id: string
name: null | string
}
createdAt: string
}
}
}DELETE
/Withdraws your own request to see someone's location.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
userIdA member's user id (
usr_…).
Errors
400Not a person's id.403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/requests/out/{userId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
withdrawn: boolean
}GET
/{ alerts }: the person's arrive and leave alerts on people they see.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/alerts' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
alerts: {
alertId: string
subjectId: string
name: string
lat: number
lon: number
radiusM: number
on: "arrive" | "leave" | "both"
repeat: boolean
createdAt: string
}[]
}POST
/Tells you when someone who shares their location with you arrives at or leaves a place: subjectId, name, lat, lon, radiusM (100 to 50,000; at least 2,000 for an approximate share), on (arrive, leave or both) and repeat. They are told an alert was set. 404 when they don't share with you; at most 20 alerts. 201.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Request body
subjectIdstringrequiredUp to 80 characters.
namestringrequired1–60 characters. Trimmed.
latnumberrequired-90–90.
lonnumberrequired-180–180.
radiusMintegerrequired100–50000.
on"arrive" | "leave" | "both"requiredrepeatbooleanDefault
false.
Also checked: Unknown fields are rejected.
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/alerts' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"subjectId": "<subjectId>",
"name": "Example",
"lat": 1,
"lon": 1,
"radiusM": 1,
"on": "arrive"
}'Send it from this page with your session or a key.
Response 201
{
alertId: string
subjectId: string
name: string
lat: number
lon: number
radiusM: number
on: "arrive" | "leave" | "both"
repeat: boolean
createdAt: string
}DELETE
/Removes one of your alerts.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
alertIdA Find My alert's id (
pal_…), asGET /v1/me/findmy/alertslists it.
Errors
400Not an alert id.403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/alerts/{alertId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
deleted: boolean
}GET
/{ phones, cars }: the person's phones (each signed-in phone and each that reports a location: last location, battery, last seen, their Find My choices; theirs alone), and their Personal cars and the cars shared with them, each where they may see it (Vehicles' privacy), with their own watches on it. Cars come only where Vehicles is on.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Errors
403Find My is yours: open it in the Maps app.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:read403Find My is for people, not keys.
curl 'https://api.cactive.com.au/v1/me/findmy/devices' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
phones: {
deviceId: string
name: null | string
model: null | string
platform: string
signedIn: boolean
lastSeenAt: null | number
mode: null | string
findMy: boolean
lastReportAt: null | number
location: null | {
lat: number
lon: number
accuracyM: number
at: number
battery?: number
charging?: boolean
}
offline: boolean
notifyWhenFound: boolean
history: boolean
}[]
cars: {
watches: {
leftBehind: boolean
found: boolean
}
vehicleId: string
name: string
model?: string
owned: boolean
ownerSpace: string
state?: string
soc?: number
lastSeen?: number
position?: {
lat: number
lon: number
accuracyM?: number
approximate?: true
headingDeg?: number
place?: string
at?: number
}
precision: "hidden" | "exact" | "approximate"
capabilities: string[]
offline: boolean
colour?: string
art?: string
picture?: {
views: {
"3qtr"?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
side?: {
srcset: object[]
box: {
x: number
y: number
w: number
h: number
}
}
}
approximate?: true
source: string
}
}[]
}POST
/Plays a sound on one of the person's signed-in phones: one push, there alone (time-sensitive). 202 { sent }.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Errors
403Find My is yours: open it in the Maps app.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
curl -X POST 'https://api.cactive.com.au/v1/me/findmy/devices/phones/{deviceId}/sound' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 202
{
sent: boolean
}PATCH
/A phone's Find My choices: notifyWhenFound (only while it's offline; its next report tells you, once) and history (off forgets it).
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Request body
notifyWhenFoundbooleanhistoryboolean
Also checked: Unknown fields are rejected. Say what to change.
Errors
403Find My is yours: open it in the Maps app.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
curl -X PATCH 'https://api.cactive.com.au/v1/me/findmy/devices/phones/{deviceId}' \
-H "Authorization: Bearer $CACTIVE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"notifyWhenFound": true,
"history": true
}'Send it from this page with your session or a key.
Response 200
{
phone: {
deviceId: string
name: null | string
model: null | string
platform: string
signedIn: boolean
lastSeenAt: null | number
mode: null | string
findMy: boolean
lastReportAt: null | number
location: null | {
lat: number
lon: number
accuracyM: number
at: number
battery?: number
charging?: boolean
}
offline: boolean
notifyWhenFound: boolean
history: boolean
}
}GET
/The phone's own fixes, the last day's, oldest first, when you keep its history. Yours alone.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
deviceIdDevice id: an agent's (
dev_…); under/v1/me/notificationsa phone's install id; under/v1/me/sign-in-approvalsa phone that approves sign-ins (apd_…); under/v1/me/vaultthe id a device made for its vault (22 base64url characters).
Errors
403Find My is yours: open it in the Maps app.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:read
curl 'https://api.cactive.com.au/v1/me/findmy/devices/phones/{deviceId}/history' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
history: boolean
points: {
lat: number
lon: number
accuracyM: number
at: number
}[]
}PUT
/Notify When Left Behind for a car you may see the location of: you're told when it drives off without the phone that shares your location, or that phone leaves it parked away from home. PUT pairs, DELETE unpairs.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.
Errors
403Find My is yours: open it in the Maps app.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:write404No such car.404No such car, or you can't see where it is.
curl -X PUT 'https://api.cactive.com.au/v1/me/findmy/devices/cars/{vehicleId}/left-behind' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
leftBehind: boolean
}DELETE
/Unpairs a car from Notify When Left Behind.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.
Errors
403Find My is yours: open it in the Maps app.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
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/devices/cars/{vehicleId}/left-behind' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
leftBehind: boolean
}PUT
/Notify When Found for a car you may see the location of, while it's offline: its next position tells you, once.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.
Errors
403Find My is yours: open it in the Maps app.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:write404No such car.404No such car, or you can't see where it is.409That car isn't offline: Find My shows where it is.
curl -X PUT 'https://api.cactive.com.au/v1/me/findmy/devices/cars/{vehicleId}/found' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
found: true
}DELETE
/Disarms Notify When Found on a car.
- Auth
- A person's token or an API key, as Authorization: Bearer.
Path parameters
vehicleIdA vehicle's id (
veh_…): one owner's period with one VIN. Another owner of the same car has another id.
Errors
403Find My is yours: open it in the Maps app.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:write404No such car.
curl -X DELETE 'https://api.cactive.com.au/v1/me/findmy/devices/cars/{vehicleId}/found' \
-H "Authorization: Bearer $CACTIVE_TOKEN"Send it from this page with your session or a key.
Response 200
{
found: false
}