Read-only access to your vehicles' positions, trips and alerts, for your own systems: a fleet-management app, an ERP, a dashboard. Version 1.
1. In Waypoint, open Manage → API keys and create a key. Copy it straight away: it is shown once and cannot be recovered, only replaced.
2. Call the API with your key. Base address: https://YOUR-WAYPOINT-ADDRESS/public/v1
curl -H "Authorization: Bearer wpk_your_key_here" \
https://YOUR-WAYPOINT-ADDRESS/public/v1/vehicles
Machine-readable description: /public/v1/openapi.json (OpenAPI 3).
Send the key in the Authorization header as a bearer token. Keys start with wpk_. Never put a key in a web address.
A key can have an expiry date and a list of allowed IP addresses. It stops working when it is revoked, when it expires, or when the account loses its API access.
| Scope | Allows |
|---|---|
read | Vehicles, positions, routes, trips. Every key has this. |
alerts | The alert feed (SOS, power cut, geofence, overspeed and so on). |
There are no write operations in version 1: no commands, no changes.
/vehiclesYour licensed vehicles with their latest position. Query: limit (default 200, up to 1000), offset.
{
"total": 1, "limit": 200, "offset": 0,
"vehicles": [{
"id": 7, "name": "Van A", "plate": "GR-1234-24", "make": "Toyota", "model": "Hiace",
"category": "van", "status": "online", "lastUpdate": "2026-10-26T10:15:02Z", "group": "Deliveries",
"position": { "latitude": 5.6037, "longitude": -0.187, "speedKmh": 42.0, "courseDegrees": 90,
"valid": true, "satellites": 11, "address": "Ring Road, Accra" },
"ignition": true, "moving": true, "stateSince": "2026-10-26T10:02:11Z", "stateAtLeastSince": null,
"odometerKm": 48210.4, "totalDistanceKm": 1204.9, "todayDistanceKm": 38.2,
"fuel": { "value": 61.0, "unit": "%" },
"batteryVoltage": 12.6, "powerVoltage": 13.1,
"licence": { "type": "annual", "tier": "core", "expiresAt": "2027-03-01T00:00:00Z" }
}]
}
status is online, offline or unknown. Fields that a vehicle's tracker does not report are null. stateSince is when moving last changed. When it has not changed for longer than we keep track of (a few days), stateSince is null and stateAtLeastSince says how far back it is known to have lasted. Positions are refreshed every few seconds; asking more often than every 5 seconds returns the same data.
/vehicles/{id}One vehicle, same shape. 404 if it is not yours or not licensed.
/meYour key's name, scopes, expiry, account and rate limit.
/vehicles/{id}/route?from=…&to=…Position history, oldest first. from and to are ISO 8601 times (UTC), at most 7 days apart. limit defaults to 5000 (up to 20000); if there are more points, truncated is true, so ask for a shorter window.
curl -H "Authorization: Bearer $KEY" \
"https://YOUR-WAYPOINT-ADDRESS/public/v1/vehicles/7/route?from=2026-10-25T00:00:00Z&to=2026-10-26T00:00:00Z"
{ "vehicleId": 7, "from": "...", "to": "...", "count": 2, "truncated": false,
"points": [ { "time": "2026-10-25T06:01:10+00:00", "latitude": 5.6, "longitude": -0.18,
"speedKmh": 0.0, "courseDegrees": 0, "altitude": 61, "valid": true } ] }
/vehicles/{id}/trips?from=…&to=…Trips between two times (up to 92 days): start, end, distance in km, duration in seconds, average and maximum speed, and start and end addresses and coordinates.
/alerts?since=…&limit=…Needs the alerts scope. Alerts from since (default: the last 24 hours, at most 7 days back), newest first, for all your licensed vehicles. Types: sos, powerCut, powerRestored, lowBattery, vibration, overspeed, geofenceEnter, geofenceExit, ignitionOn, ignitionOff, offline, online, longIdle, fuelRefill, fuelDrop, maintenanceSoon, maintenanceDue.
{ "since": "2026-10-25T10:00:00+00:00", "count": 1, "alerts": [
{ "id": "e4412", "type": "geofenceExit", "label": "Left geofence", "time": "2026-10-26T08:02:40+00:00",
"vehicleId": 7, "vehicle": "Van A", "detail": "Depot", "speedKmh": 18.4, "latitude": 5.6, "longitude": -0.18 } ] }
To avoid repeats, remember the newest time you have processed and pass it as since next time; use id to ignore an alert you already have. Push notifications to your own server (webhooks) are planned.
Each key may make a number of calls per minute that grows with the account's licensed vehicles: 12 per vehicle, at least 60 and at most 3000. Every response carries X-RateLimit-Limit. Over the limit you get 429 and a Retry-After header (seconds). Poll positions no more than every 10 to 30 seconds; for history, ask for the window you need once.
Every call is logged against its key (time, path, result, address) and shown in Waypoint under the key's call log, kept for 30 days.
Errors are JSON: { "detail": "…" }.
| Code | Meaning |
|---|---|
| 400 | A parameter is wrong (for example a time range that is too long). |
| 401 | No key, a wrong key, or a key that is revoked, expired or whose issuer is no longer active. |
| 403 | The key lacks the scope, is used from an address that is not allowed, or the account has no API access (the message says why). |
| 404 | The vehicle is not yours, is not licensed, or does not exist. |
| 429 | Too many calls. Wait for Retry-After seconds. |
Use a key only from a server you control, never in a web page or mobile app. Give each system its own key so you can revoke one without breaking the others. Add the server's IP address to the key's allowed list. If a key may have leaked, revoke it in Manage → API keys; it stops working immediately.