HTTP API — overview

The HTTP API is the core of the Destiny platform. If you're reading, listing, creating, or updating something day-to-day, it's almost certainly here. The other collections (Geo, History, SSE) are specialised — most integrations spend 80% of their time in HTTP API.

This guide is an orientation

The HTTP API in the Reference has the complete list of endpoints in this collection — every parameter, request body, response schema, and a copy-paste code sample for each. If you can't find what you need below, browse the Reference: there's a lot more there.

What it contains

Resource	What it represents
Units	Physical tracking devices on vehicles or assets
Vehicles	The asset being tracked (a truck, car, trailer)
Unit Groups / Vehicle Groups	User-defined groupings for bulk operations and reporting
Drivers	People assigned to vehicles
Clients	The end customer who owns vehicles and drivers
Unit Commands	Commands you can send to a unit (lock, immobilise, etc.)
Unit Safe Zones / Vehicle Safe Zones	Per-vehicle/unit geofences
Monitoring	Live "where is it right now" snapshots
Reports	Generate PDFs (debrief, expenditure, position log, etc.)
Dashboards	User-configurable dashboard widgets
Vehicle Expenses / Expense Types	Fuel, maintenance, fees recorded against a vehicle

A Unit ≠ a Vehicle: a unit is the hardware, a vehicle is the asset. Units are allocated to vehicles. This is why you'll see telemetry endpoints addressed by unit and by vehicle.

Patterns you'll see everywhere

List vs find vs scoped listing

Almost every resource has multiple ways to query it:

• */listing — a paged list of everything you can see.
• find/* — search/filter by name or other criteria.
• */listing/by-client/{client_id}, by-group/{group_id}, by-partner/{partner_id} — same list, scoped to one parent. Use the most specific one for your context — it's faster and returns less data.

The Form-Data pattern

Anything with Create or Edit operations has a companion Get * Create/Edit Form Data endpoint that returns the option lists and field metadata needed to build the form. See Form-Data Pattern for why and how.

Telemetry — four ways to ask

You can fetch a unit's current telemetry by:

• GET /units/{id}/telemetry (by id)
• GET /units/by-imei/{imei}/telemetry
• GET /units/by-serial/{serial}/telemetry
• GET /vehicles/{id}/telemetry (resolves through the allocated unit)

Pick whichever id you already hold.

Try it

Authenticate first (see Getting Started), then:

# List your units
curl https://www.acmdestiny.net/api/v1/units/listing \
  -H "Authorization: bearer YOUR_TOKEN"

# Get a single vehicle
curl https://www.acmdestiny.net/api/v1/vehicles/{id} \
  -H "Authorization: bearer YOUR_TOKEN"

# Live snapshot of a vehicle's primary unit (single GET — not a stream)
curl https://www.acmdestiny.net/api/v1/monitoring/vehicle/{id}/primary \
  -H "Authorization: bearer YOUR_TOKEN"

When to use a different collection

• Past data over a time range → History Query API.
• Lat/lng → address, or geofences → Geo API.
• Live, ongoing telemetry stream → Streaming (SSE).

The full HTTP API surface — every endpoint, parameters and response shapes — is in the API Reference under HTTP API.